

                      BAX INDEX TO GENERAL TOPICS

        TOPIC ...............................................PAGE

        GENERAL INFORMATION .................................. 01

        DISCLAIMER ........................................... 02

        RUNNING BAX PROGRAMS ................................. 02

        ELEMENTS OF THE BAX PROGRAMMING LANGUAGE ............. 04

        CONSTANTS ............................................ 05

        VARIABLES ............................................ 05

        KEYWORDS ............................................. 05

        LABELS ............................................... 05

        OPERATORS ............................................ 06

        COMMENTS ............................................. 06

        HYBRIDS .............................................. 06

        DOUBLE VARIABLES ..................................... 06

        VIRTUAL WORDS ........................................ 06

        PRESET VARIABLES ..................................... 07

        INTERRUPTING BAX PROGRAMS ............................ 08

        BAX DATATYPES ........................................ 08

        COMPARISONS .......................................... 09

        POSSIBLE AMBIGUITIES IN SYMBOL INTERPRETATION ........ 09

        INPUT LINE EDITING ................................... 10

        CUSTOMIZING BAX ...................................... 10

        PROGRAM ERRORS ....................................... 11

        SMALL, MEDIUM AND LARGE BAX VERSIONS ................. 13

        EXTERNAL SUB-ROUTINES ................................ 14

        TEMPORARY FILE ....................................... 14





                               INDEX - 1
        


                        INDEX TO BAX KEYWORDS

        KEYWORD(S)                                          PAGE

        ARITHMETIC FUNCTIONS (ADD,SUB,MUL,DIV,REM) .......... 15

        ASCII FUNCTION ...................................... 15

        ASSIGNMENT STATEMENT ................................ 15

        CALL STATEMENT ...................................... 16

        CASEH STATEMENT ..................................... 17

        CASEI STATEMENT ..................................... 17

        CHARS FUNCTION ...................................... 18

        CLOSEIN AND CLOSEOUT STATEMENTS ..................... 18

        CLS STATEMENT ....................................... 19

        CMD STATEMENT ....................................... 19

        COLORS STATEMENT .................................... 19

        COPY STATEMENT ...................................... 20

        CURDIR FUNCTION ..................................... 21

        DOS FUNCTION ........................................ 22

        DOSVER FUNCTION ..................................... 22

        END STATEMENT ....................................... 22

        ENVGET FUNCTION ..................................... 23

        ENVSET STATEMENT .................................... 25

        ENVSIZE FUNCTION .................................... 25















                               INDEX - 2
        


                          INDEX TO BAX KEYWORDS

        KEYWORD(S)                                          PAGE

        EXECOM FUNCTION ..................................... 26

        EXIST FUNCTION ...................................... 27

        FILELIST STATEMENT, FILENAME & FILEDATA FUNCTIONS ... 27 , 28

        GOTO STATEMENT ...................................... 29

        IF STATEMENT ........................................ 29

        INPUT STATEMENT ..................................... 30

        INPUTF STATEMENT .................................... 31

        INPUTK FUNCTION ..................................... 32

        JOIN FUNCTION ....................................... 32

        LABGET FUNCTION ..................................... 32

        LCASE FUNCTION ...................................... 32

        LEAVE STATEMENT ..................................... 32

        LEFT FUNCTION........................................ 33

        LEN FUNCTION......................................... 33

        LIT FUNCTION......................................... 33

        LOC FUNCTION......................................... 34

        LOOP STATEMENT ...................................... 34

        MEMORY FUNCTION ..................................... 35

        MID FUNCTION ........................................ 36

        MONITOR FUNCTION .................................... 36

        MOVE STATEMENT ...................................... 37

        NOW FUNCTION ........................................ 37









                               INDEX - 3
        


                          INDEX TO BAX KEYWORDS

        KEYWORD(S)                                          PAGE

        NUM FUNCTION ........................................ 38

        OPENIN AND OPENOUT STATEMENTS ....................... 38

        OUTMSG STATEMENT .................................... 39

        OUTPUT STATEMENT .................................... 40

        OUTPUTF STATEMENT ................................... 40

        OVERLAY FUNCTION .................................... 41

        PARSE FUNCTION ...................................... 41

        PATHFIND FUNCTION ................................... 42

        POS FUNCTION ........................................ 43

        REBOOT STATEMENT .................................... 43

        RIGHT FUNCTION ...................................... 43

        RETURN STATEMENT .................................... 43

        RPT FUNCTION ........................................ 44

        STOP STATEMENT ...................................... 44

        SWAP STATEMENT ...................................... 44

        TEST FUNCTION ....................................... 45

        TRANS FUNCTION ...................................... 45

        TRIM, TRIML, TRIMR FUNCTIONS ........................ 46

        UCASE FUNCTION ...................................... 46

        VERIFY FUNCTION ..................................... 46

        WHEN STATEMENT ...................................... 46

        WORD FUNCTION ....................................... 48

        WORKAREA FUNCTION ................................... 49

        WORKGET FUNCTION .................................... 50

        WORKSET STATEMENT ................................... 51



                               INDEX - 4
        
                        BAX INTERPRETER VERSION 2.1 FOR DOS        PAGE  1

                                GENERAL INFORMATION

        BAX is an interpretive programming language which can be used to
        write programs "stand alone" or for inclusion in DOS BAT files.
        There is more than one technique for running BAX programs in
        conjunction with BAT files.  These are enumerated and explained with
        examples in the section entitled "RUNNING BAX PROGRAMS".  There are
        also several sample programs included on the distribution diskette.

        Here are some things you should know about BAX.

        PROGRAM AUTHOR:               FELIX JAMES
                                      P.O. BOX 232388
                                      SACRAMENTO, CA 95823

        BAX.EXE FILE SIZE   (APPROX)   27K
        DISK SPACE REQUIRED (APPROX)  500K (SEE NOTE BELOW)
        MAXIMUM PROGRAM SIZE:          *** (SEE NOTE BELOW)
        MAXIMUM NUMBER OF VARIABLES:   999 (SEE NOTE BELOW)
        MAXIMUM LENGTH OF STRINGS:     128 CHARACTERS
        STRING MANIPULATION FUNCTIONS  YES (LOTS OF THEM)
        ARITHMETIC                     LONG INTEGER
        STRUCTURED LOOPS               YES
        SUB-ROUTINES                   YES (INTERNAL AND EXTERNAL)
        INPUT LINE EDITING             YES
        FILE I/O                       YES (ASCII TEXT ONLY)
        FILE / DIRECTORY INFORMATION   YES
        GRAPHICS                       NO
        PROGRAM CODE CASE SENSITIVE    NO
        MIXED CASE DATA                YES -- OPTIONAL
        COLOR                          YES -- 16 STANDARD COLORS
        LOGIC                          YES -- SINGLE LINE IF -- THEN -- ELSE
                                              BLOCK STRUCTURED WHEN
                                              AND A MULTIPLE TEST FUNCTION

        While the files on the BAX distribution disk consume over 500K,
        less than 100K are actually required to effectively use BAX.  Many
        of the files are help files, sample programs, etc which are actually
        not necessary for BAX to function.

        It is difficult to say how large a program might be possible, but
        we've successfully executed programs which contained over 500 lines
        of code.

        The number of variables which can be defined for a given program is
        initially set to 256, but this is increasable/decreasable by the
        user in the range 064 - 999.

        BAX requires DOS 3.00 or above.  DOS 3.30 is recommended.








          COPYWRITE 1992 - 1994 ALL RIGHTS RESERVED, FELIX JAMES   PAGE  1
        
                        BAX INTERPRETER VERSION 2.1 FOR DOS        PAGE  2

                          DISCLAIMER AND OTHER LEGAL STUFF

        The entire BAX package is Copyright 1992 - 1994 by Felix James.

        This package consists of a diskette containing Version 2.1 of the
        BAX.EXE file and a number of other files which are help files,
        sample programs written in the BAX language, and some other assorted
        documentation and utilities.

        The user is completely responsible for determining the fitness of
        BAX to perform any given task on his/her machine.  The author is
        not responsible for any damages of any kind arising from the
        failure of BAX to perform as the user expects it to.

        Remember that BAX is a programming language, and writing a bad
        program in BAX is just like writing a bad program in any other
        language.  You can damage or destroy your files if you are not
        careful.

                                RUNNING BAX PROGRAMS

        The BAX interpreter is the file BAX.EXE, which is the only file
        you actually need to run BAX programs. The rest of the files on
        the distribution disk are sample programs, help files, etc.

        Step 0 is of course to install BAX. Simply copy the files from the
        distribution disk to some convenient directory on your hard drive.
        You could do your initial testing directly from the distribution
        disk, but BAX will perform much better from a hard drive.
        It's also a good idea to make a backup copy of the diskette.
        If you are really short on disk space, you do not need the help
        files on your hard drive.  These can be printed directly from
        the diskette.  BAX does not need them to execute.

        If you want to be able to run BAX from any directory on your
        system, simply put BAX.EXE in a directory which is in the DOS
        search path. BAX program files, no matter what their extensions
        are, should also be in a directory in the DOS search path, but
        they need not be in the same directory as BAX.EXE.

        The first thing you must do to execute a BAX program is write one
        or you can run one of the sample programs on the distribution
        diskette.  Some of these may require minor modification to account
        for the specific file/directory structure of your system.  Ideally,
        a text editor such as EDLIN (UGH) or EDIT (supplied with DOS 5/6)
        should be used. If you are now writing BAT files, write your BAX
        programs using the same tool.

        Let's say that you have a program called MYPROG.TXT ready to run.
        You can execute it by typing:

        BAX MYPROG.TXT





          COPYWRITE 1992 - 1994 ALL RIGHTS RESERVED, FELIX JAMES   PAGE  2
        
                        BAX INTERPRETER VERSION 2.1 FOR DOS        PAGE  3

        If you have any arguments which you want passed to your program,
        simply include them on the command line after the file name.

        BAX MYPROG.TXT JOHN MARY SUE

        All command line information available to the BAX.EXE program is
        passed on to your program.  In this case, the arguments JOHN ,
        MARY , and SUE are assigned to the special preset variables
        %A1 , %A2 , AND %A3.  The number of arguments passed to your
        program is available in the variable %LA (last argument).
        In this case %LA would equal 3 (we don't count the file name).
        The file name itself is also available in another special variable
        called %PN (program name).  See the section entitled "PRESET
        VARIABLES" for a complete list of the information available
        to your program at run time.

        If you want your program to be executable by simply typing its
        name without having to type BAX in front of it, you can make a
        one line BAT file with the appropriate name, which contains the
        necessary call to BAX.EXE.  If you create the following BAT file,
        your BAX program can be executed by simply typing MYPROG followed
        by any arguments which your program needs.

        @BAX MYPROG.TXT %1 %2 %3 %4 %5 %6 %7 %8 %9

        Provided that the one line BAT file has the same name as your
        BAX program, we can get a little more sophisticated and use the
        BAT file argument %0 instead of actually putting our BAX progran
        file name in the BAT file.

        @BAX %0.TXT %1 %2 %3 %4 %5 %6 %7 %8 %9

        This doesn't really buy us a whole bunch, except that if we decide
        to rename our program at some point, all we have to do is rename
        the files MYPROG.BAT and MYPROG.TXT.  We don't have to change the
        actual contents of either one, unless we also changed the extension
        of the file which contains our BAX program.

        This isn't bad, but we need a one line BAT file for each BAX program
        that we have.  If we have a lot of them we are going to have a
        severe case of "directory clutter".  Not only that, but each one of
        those little files is going to use at least 2048 bytes of our
        hard drive space; even more on larger hard drives.

        There is a solution to this problem which is elegant in its
        simplicity (I know, trite phrase).  We can simply include the BAX
        program code in the BAT file which executes the BAX.EXE program.
        The following BAT file (BAXMSG.BAT) is included on the distribution
        disk, but it is short enough to include here also.








          COPYWRITE 1992 - 1994 ALL RIGHTS RESERVED, FELIX JAMES   PAGE  3
        
                        BAX INTERPRETER VERSION 2.1 FOR DOS        PAGE  4

        1)    @ECHO OFF
        2)    BAX %0 %1 %2 %3 %4 %5 %6 %7 %8 %9
        3)    GOTO SKIPBAX
        4)    =BAXPROG       'BAX PROGRAMS MUST START WITH A LABEL
        5)    OUTPUT ***** BAX PROGRAM %PN IS NOW EXECUTING *****
        6)    END            'BAX PROGRAMS MUST END WITH AN END STATEMENT
        7)    :SKIPBAX

        Line 2 is the call to the BAX.EXE file.  Notice that we did not
        specify a file extension after %0.  This was not necessary since BAX
        assumes an extension of BAT if an extension is not specified.  Line
        3 branches around (jumps over) the BAX program contained on lines 4,
        5, and 6. This is necessary because the BAT file processor
        (COMMAND.COM) will choke on the BAX program statements.  Line 7 is
        the target of the BAT file GOTO command on line 3.

        The reason that BAX does not choke on lines 1, 2, 3 and 7 which are
        BAT file statements is that BAX processing does not start until a
        BAX label is found.  BAX processing stops when an END statement is
        found.  Everything else in the file is ignored by BAX.

                    THE ELEMENTS OF THE BAX PROGRAMMING LANGUAGE

        The BAX language is composed of statements which are stored in an
        ordinary ASCII text file.  No more than one BAX statement may appear
        on any single record of the file.

        The first statement in a BAX program must be a label.
        The last  statement in a BAX program must be an END statement.

        BAX statements are subdivided into words.  A word is a group of
        characters, separated from the words before and after it in the
        statement by one or more blanks, just as the words in this sentence
        are.  (The first word in a record need not have a beginning blank,
        nor does the last word in a record require an ending blank.)  BAX
        program statements can contain a maximum of 20 words.  Each word
        falls into one of the following categories.

        1) CONSTANTS  -- symbols which define their own values
        2) VARIABLES  -- symbols which represent something else
        3) KEYWORDS   -- symbols which have special meaning to BAX
        4) LABELS     -- symbols used in altering the normal sequence of
                         statement execution
        5) OPERATORS  -- special symbols used to make comparisons or to
                         declare equality
        6) COMMENTS   -- these are normal english phrases inserted into
                         the program for documentation purposes
        7) HYBRIDS    -- a constant and a variable joined together
        8) DOUBLE VARIABLES -- two variables joined together
        9) VIRTUAL WORDS    -- words as they exist after all variable
                               substitutions have been made

        Let's expand a bit on the above "in a nutshell" definitions.




          COPYWRITE 1992 - 1994 ALL RIGHTS RESERVED, FELIX JAMES   PAGE  4
        
                        BAX INTERPRETER VERSION 2.1 FOR DOS        PAGE  5

                                     CONSTANTS

        1) The value of a constant is its name.
        2) Constants may never contain blanks, leading, trailing or imbedded
        3) Constants may never contain single quote marks:  '
        4) Constants may contain the characters:   %  =  <  >  provided
           that their placement is such that they cannot qualify the constant
           as a variable, double variable, hybrid or operator.
        5) The maximum length of a constant is 128 characters

                                     VARIABLES

        1) The value which a variable represents may change during the
           execution of a program.
        2) A variable name may never contain leading, trailing, or imbedded
           blanks but the value which it represents, can.
        3) The maximum length of a variable is 12 characters
        4) The first character must be a per cent sign ( % )
        5) The second character must be a letter ( A - Z ).
        6) The rest of the characters may be either letters ( A - Z ) or
           numbers ( 0 - 9 ).
        7) At execution time, the value which the variable represents is
           substituted for the variable name in each statement as the
           statement is executed.

                                      KEYWORDS

        1) Keywords are symbols which have special meaning to BAX.
        2) Keywords may be divided into two categories: functions,
           and statement names.
        3) Keywords may not be represented by variables in BAX statements.

                                       LABELS

        1) Labels are symbols which are targets for the GOTO, LOOP and
           CALL statements.
        2) They provide a means of altering the sequence of execution
           of the statements in a BAX program.
        3) The maximum length of a label is 12 characters.
        4) The first character must be an equal sign ( = ).
        5) The second character must be a letter ( A - Z ).  The rest
           of the characters may be any combination of letters ( A - Z ),
           or numbers ( 0 - 9 ).
        6) Labels will typically appear at the beginning of a statement
           or they will follow the keywords GOTO, CALL and LOOP.
        7) The first statement in a BAX program must be a label.











          COPYWRITE 1992 - 1994 ALL RIGHTS RESERVED, FELIX JAMES   PAGE  5
        
                        BAX INTERPRETER VERSION 2.1 FOR DOS        PAGE  6

                                     OPERATORS

        1) Operators are symbols which indicate that a comparison of two
           values is to be made, or indicate equality of two values.
        2) The characters which are recognized by BAX as operators are:
                                 =    <    >
        3) The BAX comparison operators are defined in the discussion of
           the IF and WHEN statements.
        4) The "=" sign is also used as the second word of the ASSIGNMENT
           statement to declare the equality of two values.
        5) Operators may not be represented by variables in BAX statements.

                                      COMMENTS

        1) A comment always begins with a single quotation mark ( ' ).
        2) A comment can be appended to any BAX statement.
        3) If a single quote appears as the first non-blank character
           of a statement then the entire statement line is a comment.
        4) Comments have no effect on the execution of a BAX program.
           They are completely ignored by BAX.  Their only purpose is to
           provide a means for the programmer to document his/her code.

                                      HYBRIDS

        1) A hybrid is a symbol consisting of a constant and a variable
           joined to form a single word.
        2) The first part of the word is a constant, and the second part
           is a variable.
        3) At execution time, the variable name is replaced by the value
           which it represents, creating a virtual word in place of the
           hybrid word.

                                  DOUBLE VARIABLES

        1) Double variables are symbols which consist of two variables
           joined together to form one word.
        2) At execution time, the second variable (the one on the right) is
           replaced by its value, creating a single variable name which
           is different from the original variable names.  This variable
           is then replaced by its value, creating a virtual word.

                                   VIRTUAL WORDS

        1) Virtual words are words as they exist after all applicable
           variable substitutions have been made.
        2) Like constants, the values they represent are themselves.
        3) Unlike constants, they may contain leading, trailing, or
           imbedded blanks.









          COPYWRITE 1992 - 1994 ALL RIGHTS RESERVED, FELIX JAMES   PAGE  6
        
                        BAX INTERPRETER VERSION 2.1 FOR DOS        PAGE  7

                                  PRESET VARIABLES

        When your BAX program gets control, some variables have already been
        assigned values.  You can use these variables any way you wish,
        including re-assigning different values to them, although there are
        some caveats in doing this, as we shall see.

        The variable %LINE contains the characters passed to BAX.EXE as
        arguments.  No editing is done on these characters.

        The variable group %A1 thru %A20 (20 variables) is used to pass
        command line arguments to your program.  Let's say your program
        file is MYPROG.BAT and it is executed from the DOS command line
        by typing:

        MYPROG HORSES COWS GEESE PIGS DUCKS

        Your program would have access to these values:

        %LINE     would equal  MYPROG HORSES COWS GEESE PIGS DUCKS
        %A1       would equal  HORSES
        %A2       would equal  COWS
        %A3       would equal  GEESE
        %A4       would equal  PIGS
        %A5       would equal  DUCKS
        %LA       would equal  5                 (5 arguments passed)
        %PN       would equal  MYPROG.BAT        (can vary, see notes below)
        %B        would equal  one blank         (handy)
        %N        would equal  a null string     (also handy)
        %EOF      would equal  0                 (End of File indicator)
        %EOI      would equal  0                 (End of Input indicator)

        The %PN variable contains the filespec used by BAX.EXE to open the
        file which contains your BAX program.  The %PN variable could have
        an extension other than BAT, depending on what method you use for
        executing your BAX programs.  It will in most cases, have a DOS path
        in front of the filename.

        The %B and %N variables are provided as a coding convenience.

        The %EOF variable is one that probably should not be re-assigned,
        since it is used by the FILE I/O routines to tell you if you have
        reached the end of the file you are reading.  It will normally equal
        0, but will change to 1 when an end of file condition occurs.

        The %EOI variable is reset each time an INPUT statement is
        executed.  It indicates if the user exited from input mode by
        pressing ENTER (%EOI = 0) or by pressing ESCAPE (%EOI = 1).









          COPYWRITE 1992 - 1994 ALL RIGHTS RESERVED, FELIX JAMES   PAGE  7
        
                        BAX INTERPRETER VERSION 2.1 FOR DOS        PAGE  8

                             INTERRUPTING BAX PROGRAMS

        If your BAX program gets stuck in a loop, the PANIC button(s) are
        CTRL-BREAK.  Holding the control key down while pressing the BREAK
        key will immediately stop your BAX program from running, if it is in
        fact the currently executing program.  If you have called another
        program from within BAX, it may be the other program which has
        control at the moment.  There is also the possibility that the loop
        is in the BAT file which called BAX.  Make sure that you read the
        documentation for any other programs which you might be using in
        conjunction with BAX to learn how to escape from them if they start
        looping.

                                   BAX DATATYPES

        BAX has only one datatype  -- character strings.  All values are
        stored in string format.  If a calculation is required, the string
        values specified are converted to numeric values, the result
        calculated, and then the numeric result is converted to string
        format and assigned to the appropriate variable.

        This brings up an interesting point which you should be aware of.
        We can best illustrate it with an example.

        %X = 005         ' NUMBER WITH LEADING ZERO FILL
        %X = ADD %X 1    ' INCREMENT THE NUMBER
        OUTPUT %X        ' DISPLAY THE RESULT

        The displayed result will be:   6       (not)       006.

        The same caveat applies to numeric strings with leading or trailing
        blank fill.  The fill characters will not survive a calculation.
        You can of course do the following or something equivalent:

        %X = 005              ' STARTING VALUE
        %X = ADD %X 1         ' RESULT:  %X = 6
        %X = JOIN 00000 %X    ' RESULT:  %X = 000006
        %X = RIGHT %X 3       ' RESULT:  %X = 006

        Sometimes we might want to eliminate the leading zero fill.  To do
        this, simply make a calculation which does not change the value.

        %X = 005
        %X = ADD %X 0         ' RESULT:  %X = 5













          COPYWRITE 1992 - 1994 ALL RIGHTS RESERVED, FELIX JAMES   PAGE  8
        
                        BAX INTERPRETER VERSION 2.1 FOR DOS        PAGE  9

                                    COMPARISONS

        BAX makes comparisons when the IF or WHEN statements are executed,
        and also when the TEST function is called.  It is important that the
        BAX programmer understand how the comparisons are made, because
        there are some potentially confusing situations in this area.  When
        it becomes necessary to compare two values, this is the procedure.

        1. Each value is tested to see if it is a number.
        2. If both values are numbers, then a numeric comparison is made,
           and the true / false value of the comparison determined.
        3. If either of the values is not a number, then a string comparison
           is made, and the true / false value of the comparison determined.

        Some typical comparisions and their results are listed below.

        Comparison          String/Numeric   True/False   Comments

        5      > 7          numeric          false        Simple case

        JUNK   < TRASH      string           true         Simple case

        ZZZ    > aaa        string           false        See CASEH, CASEI

        5      = 0005       numeric          true         See 1,2 above

        aaa    = AAA        string           false        See CASEH, CASEI

                   POSSIBLE AMBIGUITIES IN SYMBOL INTERPRETATION

        Because of BAX's simple syntax, ambiguity in interpretation of some
        symbols is likely in a few situations.  For example, if you want
        some of the special prefix characters ( = % ' ) to be treated as
        literal characters in constants, rather than their normal meaning.

        These situations can usually be worked around by assigning the
        troublesome character to a variable and then when the character is
        required in a subsequent statement, code the variable name which
        represents the character rather than the character itself.  We'll
        cite one example to illustrate the technique.

        Suppose we want to output the sentence:  DON'T DO THAT!  to the
        screen.  If we code it like this:

        OUTPUT DON'T DO THAT!

        What will be displayed on the screen will be:       DON
        because BAX assumes anything after a single quote mark is a comment.
        We can get around this by doing the following.

        %SQ =   CHARS 39           ' ASCII CODE FOR SINGLE QUOTE = 39
        %DONT = JOIN DON %SQ T     ' JOIN THE 3 PIECES OF THE STRING
        OUTPUT %DONT DO THAT!      ' OUTPUT WILL BE:   DON'T DO THAT!




          COPYWRITE 1992 - 1994 ALL RIGHTS RESERVED, FELIX JAMES   PAGE  9
        
                        BAX INTERPRETER VERSION 2.1 FOR DOS        PAGE 10

                                 INPUT LINE EDITING

        When you use the INPUT statement, your program pauses while the
        user enters or modifies a line of data.

        The left  arrow moves the cursor one character to the left.
        The right arrow moves the cursor one character to the right.
        The end key moves the cursor to the end of the line.
        The delete key deletes the character at the cursor position.
        The insert key toggles insert/overstrike mode.
        (When in overstrike mode, the cursor is an underscore, while in
        insert mode, the cursor is a big box.)

        These are the only keys which can be used to edit the input line.
        The tab keys, control keys, etc are disabled.  The backspace key is
        equivalent to the left arrow key.  Naturally, the space bar and all
        the "visible character" keys are available for use.  The user may
        terminate editing with either the ESCAPE key or the ENTER key.  See
        the INPUT statement in the language reference for more details.

                                  CUSTOMIZING BAX

        Bax runs in upper case mode, or mixed case mode.  When running in
        upper case mode, all incoming strings are converted to upper case.
        If you prefer mixed case mode, make the second character of the
        label which starts your BAX program, a lower case character.  This
        tells BAX not to do upper case translation on your input data.
        Examples:

                         =abc     'mixed case
                         =ABC     'UPPER CASE

        If the default value of 256 variables is not enough then construct
        the beginning label of your program like one of these:

                         =a500    'mixed case, 500 variables max
                         =A310    'UPPER CASE, 310 VARIABLES MAX

        The last three characters of the label will be used as the maximum
        number of variables that your program can hold.  In the examples, we
        used the values 500 and 310 but this value can be anything between
        064 and 999. (Note the "064". Bax requires 3 characters.)

        Mixed case programming is a bit more complicated because any
        comparisons made between data elements in your program will be case
        sensitive.  BAX provides two functions for translating strings from
        upper to lower, and lower to upper case (LCASE and UCASE), and also
        the CASEH and CASEI statements may be helpful when using mixed case.

        It doesn't matter what case keywords, variables or labels are, since
        BAX processing of these program elements is not case sensitive.
        Only constants, command line arguments, and data entering the
        program through the INPUT and INPUTF statements are case sensitive.




          COPYWRITE 1992 - 1994 ALL RIGHTS RESERVED, FELIX JAMES   PAGE 10
        
                        BAX INTERPRETER VERSION 2.1 FOR DOS        PAGE 11

                                   PROGRAM ERRORS

        Most errors which occur in BAX programs are fatal (hopefully, not to
        the programmer), but to the program itself, which will terminate
        execution at the line where the error occurred.  BAX provides a way
        to test for just about every possible illegal condition that might
        occur, so if one of these conditions does occur, it means that
        something has happened that the programmer did not anticipate.
        Under such conditions, it is better to stop, allow the programmer to
        make whatever corrections need to be made and then re-execute the
        program, than to risk the execution of statements which may be
        dependent on the success of a prior statement that failed.

        Each BAX error message has a number assigned to it, which is
        displayed along with the message.  This number is returned as an
        error level to the BAT file which called the BAX program, so you can
        test to see if your BAX program terminated normally or with an error
        condition.  These error levels are in the range 100 - 199.  If you
        avoid using this range of values when your program sets its own
        error levels, you can easily test to see if the error level was set
        by your own program or was set by BAX.EXE.  See the END and STOP
        statements in the BAX language reference for specific information
        on how your program can set error levels.

        Most BAX error messages will reference the line number where the
        error occurred.  This line number represents the ordinal position
        of the line in the file which contains your BAX program.  The line
        number is not relative to the first line in the BAX program itself.
        This was done because most text editors either display or make it
        easy to check the position of any given record in the file being
        edited, but they have no knowledge of the fact that the file being
        edited has a program imbedded somewhere in it.  A list of the BAX
        error messages follows:
























          COPYWRITE 1992 - 1994 ALL RIGHTS RESERVED, FELIX JAMES   PAGE 11
        
                        BAX INTERPRETER VERSION 2.1 FOR DOS        PAGE 12

        BAX-104: VARIABLE TABLE IS FULL.  MAXIMUM IS ____ VARIABLES
        BAX-105: DUPLICATE LABEL FOUND
        BAX-106: WORD COUNT ERROR
        BAX-107: OUT OF MEMORY
        BAX-110: STRING OVERFLOW
        BAX-111: INVALID OR MISSING KEYWORD
        BAX-112: USE OF UNASSIGNED VARIABLE
        BAX-113: NUMERIC CONVERSION ERROR
        BAX-114: ILLEGAL FUNCTION CALL
        BAX-115: ILLEGAL LABEL OR ILLEGAL USE OF LABEL
        BAX-116: SUB-ROUTINE CALL / RETURN ERROR
        BAX-117: FILE NOT FOUND
        BAX-118: FILE IS ALREADY OPEN
        BAX-119: FILE IS NOT OPEN
        BAX-120: ILLEGAL MOVE OR COPY
        BAX-121: MISSING OR INVALID DATA
        BAX-122: LOOP STRUCTURE ERROR
        BAX-123: CHANGE DRIVE ERROR
        BAX-150: SYNTAX ERROR
        BAX-199: SYSTEM ERROR

        Most of these should be self explanatory, but there are a few of
        them which require a little more explanation.

        BAX-106: WORD COUNT ERROR
        This message might indicate that there are more than 20 words on a
        line, or more likely, a function that requires a certain number of
        arguments may be receiving more or less than it expects.

        BAX-110: OVERFLOW ERROR
        This message will usually be caused by attempting to use the INPUT
        statement to edit a value which is too long for the input field.
        Generally, it means that some value is too big for the space
        allocated to hold it.

        BAX-116: SUB-ROUTINE CALL / RETURN ERROR
        This message indicates one of the following conditions.
           1. A CALL statement has been made to a subroutine which is
              already active.
           2. A RETURN statement has been encountered, but no subroutine
              is currently active.
           3. Too many nested subroutines (max is 10)















          COPYWRITE 1992 - 1994 ALL RIGHTS RESERVED, FELIX JAMES   PAGE 12
        
                        BAX INTERPRETER VERSION 2.1 FOR DOS        PAGE 13

        BAX-122:  LOOP STRUCTURE ERROR
        This message indicates one of the following conditions.
        1. A LOOP statement has been encountered, but the loop is
           already active.
        2. A LEAVE statement has been encountered, but no loop is
           currently active.
        3. The label in a LOOP or LEAVE statement is above the LOOP or
           LEAVE statement in the program.

        BAX-199:  SYSTEM ERROR              ERRNUM =

        This message you may see, especially if you are using CHDRIVE,
        CHDIR, MKDIR, or RMDIR statements.  You can can easily test the
        prerequisites for their successful execution with the EXIST
        function.  You might also encounter this message if you open files
        with a DOS path supplied.  Again, you can avoid this error by using
        the EXIST function.

        Here is a list of ERRNUM values which you might see.

        ERRNUM  <-------------------PROBABLE CAUSE------------------------>
          7     OUT OF MEMORY, DOS ENVIRONMENT?  PROGRAM TOO LARGE?
         53     SPECIFIED FILE DOES NOT EXIST
         61     DISK FULL, PROBABLY NEED TO CLEAN UP A BIT
         64     BAD FILE NAME, FILENAME CONTAINS INVALID CHARS
         71     DISK NOT READY, DRIVE DOOR OPEN OR NO DISKETTE INSERTED
         75     PATH ERROR, TRIED TO DELETE A DIR ILLEGALLY (MAYBE)
         76     PATH NOT FOUND, PATH INVALID, ETC

                              SMALL, MEDIUM AND LARGE

        Your distribution disk has three different versions of BAX on it.
        Each uses a different size memory pool to store your program and
        its data while it is executing.  The different versions are:

                        Name        Memory Pool     Executing Size
                        BAX.EXE     32K             About 70K
                        BAX16.EXE   16K             About 54K
                        BAX48.EXE   48K             About 86K

        Regardless of a program's size on disk (BAX is about 27K), it will
        in most cases get more memory for itself while it is executing.

        Unless you are doing something fairly unusual, BAX.EXE with its 32K
        memory pool should do quite nicely and you need not worry about
        using the other ones, but there are situations where it might make
        sense to use one of the others.

        You might opt to use BAX16.EXE if you write very small BAX programs
        which call very large applications.  The memory that BAX is
        occupying is not available to your application, which may need all
        it can get.





          COPYWRITE 1992 - 1994 ALL RIGHTS RESERVED, FELIX JAMES   PAGE 13
        
                        BAX INTERPRETER VERSION 2.1 FOR DOS        PAGE 14

        You might opt to use BAX48.EXE if you write large BAX programs which
        use a lot of variables or assign a lot of long strings to your
        program's variables.  If your BAX programs frequently fail because
        of lack of memory, but your applications have modest memory
        requirements, so that the memory used by BAX is not a factor in your
        application's execution, it might not be a bad idea to try using
        BAX48.EXE.

        The default number of variables (256) seems to be about right for
        the 32K version, but it may be too many for the 16K version.  If
        you are using the 16K version and you run into memory problems,
        try reducing the variable maximum.  Remember, that when you are
        using the 16K version, almost every program is a large one.

        If you need to increase the number of variables above 256, you
        should probably use the 48K version.  There are no absolute
        rules enforced in this regard by BAX itself.  It is left up to
        your judgment. If you use the MEMORY function and display its
        results right at the beginning of your program, and then repeat
        this at a few more locations in your program, and then again
        at the end of your program, you will have a pretty good handle
        on what you need to do.

                                EXTERNAL SUBROUTINES

        BAX has two kinds of subroutines: Internal and External.  The
        internal subroutines are documented in the language reference
        under the CALL and RETURN statements.  These are blocks of BAX
        code which reside completely within the executing BAX program.

        External subroutines are actually separate programs which can be
        executed from your BAX program.  They can be written in just about
        any language.  They can return up to 16384 bytes of data to the
        calling BAX program, either through the use of environment variables
        or through the use of the BAX work area (a special block of memory
        which your BAX program can create).  These features are documented
        in the language reference under ENVGET, ENVSET, ENVSIZE, WORKAREA,
        WORKGET and WORKSET.

                                   TEMPORARY FILE

        The BAX DOS function writes a temporary file under some conditions.
        This file is named BAX00000.BAT and under normal circumstances is
        erased when the DOS function completes successfully.  There is
        always the possibility that because of a power failure or if the
        program being called got stuck in a loop, forcing a reboot, that the
        file would not be deleted.  It will be deleted the next time the DOS
        function completes normally, and it is nothing to worry about.  The
        only reason I mention it, is that I know that it is irritating to
        have files show up, for which there is no documented reason.  It is
        ok to delete this file from the DOS prompt, although you could get
        some unpredictable results if you delete it while a BAX program is
        active.




          COPYWRITE 1992 - 1994 ALL RIGHTS RESERVED, FELIX JAMES   PAGE 14
        
        BAX INTERPRETER VER 2.1 FOR DOS, STATEMENTS & FUNCTIONS    PAGE 15

               ARITHMETIC FUNCTIONS: ADD , SUB , MUL , DIV , REM

        What the arithmetic functions do should be fairly obvious from their
        names.  All of them accept a list of arguments which is variable in
        length.  Here are some examples. Bear in mind that we are doing
        integer arithmetic.  The fractional part of any calculation is
        truncated, no rounding is done.  The range of legal values is:
        -2,147,483,648 thru 2,147,483,647

        %V = ADD 5 3                           ' RESULT: %V =  8
        %V = SUB 9 2                           ' RESULT: %V =  7
        %V = MUL 4 7                           ' RESULT: %V = 28
        %V = DIV 8 2                           ' RESULT: %V =  4
        %V = REM 8 3                           ' RESULT: %V =  2

        %V = ADD 7 2 11 4 8                    ' RESULT: %V = 32
        %V = SUB 20 3 2 1 6                    ' RESULT: %V =  8
        %V = MUL 2 3 2 5                       ' RESULT: %V = 60
        %V = DIV 57 2 4 3                      ' RESULT: %V =  2
        %V = REM 87 35 10 2                    ' RESULT: %V =  1

        %V = DIV 7 -2                          ' RESULT: %V = -3

                                  ASCII FUNCTION

        The ASCII function returns the ASCII code of the first character
        in the argument passed to it.  The argument may not be a null
        string.  Return codes are in the range 0 - 255.

        %V = ASCII A                    ' RESULT: %V = 65

        Note: Use the CHARS function for ASCII to character translation.

                                ASSIGNMENT STATEMENT

        The ASSIGNMENT statement is used to assign values to variables.
        The first word in an assignment statement must be a variable or
        double variable.  The second word must be a single equal sign (=).
        The third word can be any of the following:

        1) a constant                             %J = MYFILE.TXT
        2) a variable                             %J = %SLUG
        3) a double variable                      %J = %COST%COUNT
        4) a hybrid                               %J = C:\MYDIR\%FILE
        5) a function name                        %J = LEFT %NAME %INDEX

        A function name will usually be followed by additional words which
        are the arguments which the function will use to generate the value
        which is to be assigned to the variable specified as word #1.








          COPYWRITE 1992 - 1994 ALL RIGHTS RESERVED, FELIX JAMES   PAGE 15
        
        BAX INTERPRETER VER 2.1 FOR DOS, STATEMENTS & FUNCTIONS    PAGE 16

        The ASSIGNMENT, INPUT, INPUTF and CALL statements are the only
        statements which can create new variables.  A variable's first
        appearance must be on the left side of the equal sign in an
        assignment statement, in an INPUT or INPUTF statement, or be
        listed following the label on the line pointed to by a CALL
        statement.  A new variable cannot appear as part of the CALL
        statement itself.

        If a double variable appears as word #1 in an assignment statement,
        the rightmost variable must be a variable which has already been
        created as described above.  Let's look at an example.

        %CHICKEN%EGG = ROOSTER

        In the above example, %EGG must have been previously created.  We
        of course can't tell the actual full name of the variable which
        begins with the characters "%CHICKEN" until the value of %EGG has
        been substituted for the symbol %EGG.  Let's say that %EGG has the
        value 23.  After substitution, the statement becomes:

        %CHICKEN23 = ROOSTER

        The variable %CHICKEN23 will be created if it does not already
        exist.  It will be assigned the value "ROOSTER" whether it
        previously existed or not.

                                   CALL STATEMENT

        The CALL statement calls an internal subroutine.  Example:

        CALL =MYSUB   'CALLS THE SUBROUTINE WHICH BEGINS AT LABEL =MYSUB

        The called subroutine must terminate with a RETURN statement.
        When the RETURN statement is executed, it returns control to the
        statement following the most recently executed CALL statement.

        There are a few rules and restrictions concerning subroutines.

        1. They cannot be called recursively.  They can't call themselves
           and they cannot be called from anywhere if they are already
           active.  An active subroutine in this context is a subroutine
           which has been called, but for which no RETURN statement has
           as yet been executed.

        2. You must not use the GOTO statement to transfer control out
           of them.  They must be terminated with a RETURN statement.
           There is nothing to stop you from using the GOTO statement
           to exit from a subroutine, but you will never be able to call
           the subroutine again, because no RETURN statement will have
           been executed to clear it from the active list.







          COPYWRITE 1992 - 1994 ALL RIGHTS RESERVED, FELIX JAMES   PAGE 16
        
        BAX INTERPRETER VER 2.1 FOR DOS, STATEMENTS & FUNCTIONS    PAGE 17

        3. You must not use the GOTO statement to transfer control into
           them, because if a RETURN statement gets executed and there
           is no active subroutine call to return to, BAX will terminate
           execution of your program.

        4. Looking at this problem from a common sense point of view, there
           really isn't any reason why you can't use a GOTO statement to
           leave a subroutine, provided it is done with the purpose of
           terminating execution of your program.  It can't possibly do any
           harm in this case.

        5. Subroutines may be nested to a level of ten.  In other words,
           subroutine A can call subroutine B which can call subroutine C
           which can call subroutine D , etc , etc.  Be careful that you
           do not attempt to call a subroutine which is already active.
           In other words, in the A-B-C-D chain described above, D cannot
           call A or B or C, because A , B , C are already active. C cannot
           call A or B, and B cannot call A, for the same reason.

        6. All variables used in subroutines are global in scope.  BAX does
           not support any kind of local or hidden variable scheme.

        You may optionally pass arguments to your sub-routines.  To do this,
        place the argument list after the label in your CALL statement.

        CALL =MYSUB %XYZ 29 XXX%J %Y%K

        As shown, arguments can be variables, constants, hybrids or double
        variables, in any order or combination .

        The statement containing the target label must have a list of
        variable names to receive the values specified in the CALL
        statement.

        =MYSUB %ABC %NUMBER %XVALUE %YKVAL

        Only simple or double variables may appear after the label in the
        statement containing the target label.  The number of arguments
        passed by the CALL statement must be exactly equal to the number of
        variables listed in the statement containing the target label.

        See the RETURN statement for information on terminating your
        subroutines.

                               CASEH AND CASEI STATEMENTS

        CASEH and CASEI tell BAX to Honor or Ignore case when comparing
        values.  No arguments are required.  Examples:

        CASEH            ' HONORS CASE
        CASEI            ' IGNORES CASE






          COPYWRITE 1992 - 1994 ALL RIGHTS RESERVED, FELIX JAMES   PAGE 17
        
        BAX INTERPRETER VER 2.1 FOR DOS, STATEMENTS & FUNCTIONS    PAGE 18

                                   CHARS FUNCTION

        The CHARS function returns a character string composed of the ASCII
        codes supplied to it as arguments.  Valid values are 0 thru 255.

        %V = CHARS 65                   ' RESULT: %V = A
        %V = CHARS 39 65 66 67 39       ' RESULT: %V = 'ABC'

        Note: Also see ASCII function.

                    CHRIVE , CHDIR , MKDIR , RMDIR STATEMENTS

        The CHDRIVE statement changes drives.  You can also change drives
        with the DOS function or CMD statement but CHDRIVE is much faster
        because there is no need to "shell out" of the BAX program.  The
        three statements:

        %V = DOS D:
        CMD D:
        CHDRIVE D

        are functionally equivalent.  All three will make the D drive the
        current drive.

        CHDIR, MKDIR, and RMDIR are the functional equivalents of their
        DOS counterparts and work exactly the same way.  Syntax is the same
        but BAX does not support the abbreviations CD, MD, and RD.  The
        same considerations as those expressed in the description of the
        CHDRIVE statement apply here.  It is faster to issue the BAX
        versions of the commands from within BAX than it is to "shell out"
        to DOS.

        It is a good idea to test for the validity of the drives and / or
        directories which you reference in these statements before you
        actually allow the statements to execute.  You can do this with
        the EXIST function, which will return different values, depending
        on whether errors were path errors or file name errors.

                         CLOSEIN AND CLOSEOUT STATEMENTS

        These statements close the files opened with the OPENIN and OPENOUT
        statements.  BAX will normally close any open files at program
        termination time anyway, but closing the files that you open is good
        programming practice in any language.  The CLOSIN statement must be
        used to close a file which was opened with the OPENIN statement.
        CLOSEOUT must be used to close a file opened with OPENOUT.

        Note: See OPENIN, OPENOUT, INPUTF, OUTPUTF









          COPYWRITE 1992 - 1994 ALL RIGHTS RESERVED, FELIX JAMES   PAGE 18
        
        BAX INTERPRETER VER 2.1 FOR DOS, STATEMENTS & FUNCTIONS    PAGE 19

                                   CLS STATEMENT

        The CLS statement clears the screen.  Example:

        CLS          ' THIS STATEMENT CLEARS THE SCREEN

        The CLS statement honors the current COLORS setting.  Only the
        background color is significant since the CLS statement in effect,
        fills the screen with blanks so the foreground color is not a
        factor.  Example:

        COLORS 14 6  'YELLOW ON BROWN
        CLS          'CLEARS THE SCREEN OF TEXT AND PAINTS IT BROWN

        See the COLORS statement for additional information.

                                    CMD STATEMENT

        The CMD statement passes a list of words to DOS for execution as
        a command.  A single blank is included between each word.  This is
        a more efficient way to issue a DOS command than by using the DOS
        function, but you do not get any return code (ERRORLEVEL).

        CMD COPY MYFILE.TXT YOURFILE.TXT

        Note: Also see the DOS and EXECOM functions.

                                  COLORS STATEMENT

        The COLORS statement assigns the foreground (text) and background
        colors to be used by the CLS, OUTPUT, OUTMSG and INPUT statements.
        Two arguments are required: 1) The foreground color
                                    2) The background color

        Colors are specified by number according to the following table.

                   0 = Black              8 = Bright Black (Gray)
                   1 = Blue               9 = Bright Blue
                   2 = Green             10 = Bright Green
                   3 = Cyan              11 = Bright Cyan
                   4 = Red               12 = Bright Red
                   5 = Magenta           13 = Bright Magenta
                   6 = Brown             14 = Bright Brown (Yellow)
                   7 = White             15 = Bright White

        Colors 8 through 15 may not be used as background colors.
        All 16 colors may be used as foreground (text) colors.










          COPYWRITE 1992 - 1994 ALL RIGHTS RESERVED, FELIX JAMES   PAGE 19
        
        BAX INTERPRETER VER 2.1 FOR DOS, STATEMENTS & FUNCTIONS    PAGE 20

        Examples:

        COLORS 14 6   'SPECIFIES YELLOW ON BROWN
        COLORS 15 1   'SPECIFIES BRIGHT WHITE ON BLUE
        COLORS  0 7   'SPECIFIES BLACK ON WHITE

        The default colors are white on black (7 on 0), so on monochrome
        monitors, the last example will create a "reverse video" effect.
        If you have a monochrome monitor, the "safe" combinations are:

        COLORS  7 0     'WHITE ON BLACK (THE DEFAULT)
        COLORS  0 7     'BLACK ON WHITE (REVERSE VIDEO)
        COLORS 15 0     'BRIGHT WHITE ON BLACK (HI-LIGHTED TEXT)

        If you stick with these, you will at least be able to see your
        text.  Monitors can differ greatly (both color and monochrome)
        so you will have to experiment a bit to find out what colors
        work best for you on your equipment.

                                   COPY STATEMENT

        The COPY statement copies one file to another.  This statement
        may only be used when both the source file name and destination
        file name are explicitly present in the statement after all
        variable substitutions have been made.  No wild cards are allowed,
        and both files must have extensions.  Examples:

        COPY MYFILE.TXT YOURFILE.TXT  'SIMPLE FORM USING CONSTANTS

        %X = MYFILE.TXT
        %Y = C:\YOURDIR\YOURFILE.TXT
        COPY %X %Y                    'SIMPLE FORM USING VARIABLES

        You can of course, also use double variables and hybrids as well
        as constants and simple variables, in any combination.

        Either or both files may contain paths.  The source file must
        currently exist, but the destination file may or may not exist.

        The COPY statement is included as a performance enhancer since it
        is totally contained within BAX.  You can also copy files by using
        the CMD statement or the DOS function, specifying the DOS COPY or
        XCOPY commands, but these both require the creation of a second
        level of DOS to execute, and as a result, are not as fast as COPY
        when copying a single file.  DOS COPY or XCOPY should be used when
        you have a group of files which can be specified by using wild
        cards, or you wish to use one or more of the special options
        available with these commands.

        Note: The COPY statement does not honor the DOS VERIFY setting.  Use
        DOS COPY or XCOPY if your system requires this feature.






          COPYWRITE 1992 - 1994 ALL RIGHTS RESERVED, FELIX JAMES   PAGE 20
        
        BAX INTERPRETER VER 2.1 FOR DOS, STATEMENTS & FUNCTIONS    PAGE 21

                                  CURDIR FUNCTION

        The CURDIR function returns the current directory path.  For
        example, if the current directory is the root directory on
        drive C, the value returned would be: C:\   If the current
        directory were the DOS directory on drive C, then the CURDIR
        function would return C:\DOS.  The CURDIR function requires
        no arguments.

        %P = CURDIR           ' RESULT: %P = C:\  (If currently in root dir)
        CHDIR \DOS            ' CHANGE TO DOS DIRECTORY
        %P = CURDIR           ' RESULT: %P = C:\DOS

             CURSORV FUNCTION ,  CURSORH FUNCTION ,  CURSORVH STATEMENT

        The CURSORV function returns the vertical position of the cursor
        on the screen.  The screen consists of 25 lines, numbered with the
        top line being number 1 and the bottom line being number 25.  The
        possible return codes from the CURSORV function are therefore in
        this range.  The CURSORV function does not require any arguments.

        %ROW = CURSORV        'RESULT: %ROW = 15 (MAYBE)

        The CURSORH function returns the horizontal positon of the cursor
        on the screen.  The screen consists of 80 columns or character
        positions, numbered from 1 to 80 with the left most column being
        number 1 and the right most column being number 80.  The possible
        return codes from the CURSORH function are therefore in this
        range.  The CURSORH function does not require any arguments.

        %COL = CURSORH       'RESULT: %COL = 47 (MAYBE)

        The CURSORVH statement positions the cursor at a particular row
        and column. Both row and column values must be specified.

        CURSORVH 12 40       'RESULT: CURSOR IS PLACED AT ROW 12, COLUMN 40

        If you only want to change one of the values (row or column), you
        may code a zero value for the one you do not wish to change.

        CURSORVH 0 22        'RESULT: ROW UNCHANGED, CURSOR AT COLUMN 22
        CURSORVH 5 0         'RESULT: CURSOR AT ROW 5, COLUMN UNCHANGED

                                 DELETE STATEMENT

        The DELETE statement is used to delete files.  It works just
        like the DOS DEL command except that it does not warn you if
        you are deleting all files in a given directory.  Another
        difference is that deleting a file which does not exist in the
        first place will not result in an error message. Wildcard
        characters (? *) may be used.

        DELETE BIGFILE.TXT       ' DELETE ONE FILE
        DELETE *.*               ' DELETE THEM ALL -- USE CAUTION



          COPYWRITE 1992 - 1994 ALL RIGHTS RESERVED, FELIX JAMES   PAGE 21
        
        BAX INTERPRETER VER 2.1 FOR DOS, STATEMENTS & FUNCTIONS    PAGE 22

                                    DOS FUNCTION

        The DOS function  passes a list of words to DOS for execution as
        a command.  A single blank is included between each word.
        The value returned is the same as the ERRORLEVEL value which is used
        in BAT files, only now, you can pick the name.

        %V = DOS COPY MYFILE.TXT YOURFILE.TXT  ' SEE NOTE BELOW
        %ERRORLEVEL = DOS DIR *.*   ' IF YOU REALLY LIKE THAT NAME
        %P = EDLIN                  ' THE DOS COMMAND WE ARE GOING TO CALL
        %X = CONFIG.SYS             ' THE NAME OF THE FILE TO PROCESS
        %RC = DOS %P %X             ' CALLS EDLIN TO MODIFY CONFIG.SYS

        Since not too many DOS commands actually return an ERRORLEVEL, it
        is usually faster to use the CMD statement to execute them.  A few
        of them do (XCOPY for instance).  Check your DOS manual to see
        which ones do and which ones don't.

        If you are executing a BAT file, there is a small performance gain
        if you include the extension (.BAT) with the program name.

        %RC = DOS MYPROG     PIGS GOATS ELEPHANTS ' WILL WORK JUST FINE
        %RC = DOS MYPROG.BAT PIGS GOATS ELEPHANTS ' BUT THIS IS FASTER

        Also see the CMD statement and EXECOM function.

                                  DOSVER FUNCTION

        The DOSVER function returns the current version of DOS running on
        the system.  The returned value is always a 3 digit number without
        a decimal point.  For example, DOS 5.00 would be returned as 500,
        while DOS 3.30 would be returned as 330.  Example:

        %DOSV = DOSVER       'RESULT:   %DOSV = 320  (IF VERSION WAS 3.20)

                                   END STATEMENT

        The first statement in a BAX program must be a label.
        The last  statement in a BAX program must be an END statement.
        This does not mean that these two statements must be the first and
        last lines in the file which contains a BAX program, since it is
        likely that any given BAX program which exists in a BAT file will
        have some standard BAT code in front of it, and it is also likely
        that some BAT code will follow it.

        It is also fairly common practice for most programmers to put some
        comments at the beginning of their programs, so using a label at the
        beginning of the BAX program and the END statement at the end of the
        BAX program allows the BAX interpreter to skip any code which is not
        actually executable BAX code.  The following program map is probably
        fairly typical.






          COPYWRITE 1992 - 1994 ALL RIGHTS RESERVED, FELIX JAMES   PAGE 22
        
        BAX INTERPRETER VER 2.1 FOR DOS, STATEMENTS & FUNCTIONS    PAGE 23

        :*********************************
        : DOCUMENTATION BOX, DESCRIBING  *
        : WHAT THE BAT PROGRAM DOES.     *
        :*********************************
        @ECHO OFF
        ..... BAT STATEMENT
        ..... BAT STATEMENT
        ..... BAT STATEMENT
        BAX %0 %1 %2 %3 %4 %5 %6 %7 %8 %9
        GOTO SKIPBAX
        ************** ANYTHING IN THIS AREA IS IGNORED BY BOTH BAT AND BAX
        =ANYLABEL
        .............. BAX STATEMENT
        .............. BAX STATEMENT
        .............. BAX STATEMENT
        END
        ************** ANYTHING IN THIS AREA IS IGNORED BY BOTH BAT AND BAX
        :SKIPBAX
        ..... BAT STATEMENT
        ..... BAT STATEMENT
        ..... BAT STATEMENT

        END will also return an ERRORLEVEL code, just like the STOP
        statement will.  The value to be returned can be either a numeric
        constant or a variable.  Examples:

        END 44           (or)        END %ERROR

                                ENVGET FUNCTION

        The ENVGET function returns the value of the specified environment
        variable(s).  One or two arguments are required.  The first one is
        either a "P" or a "C", which specifies if the environment variable
        value(s) are to be obtained from the current (child) process, or
        from the previous (parent) process.  Typically, the "parent" will be
        DOS or more correctly, COMMAND.COM.  The "child" will be your BAX
        program.  If you have not made any changes to either environment,
        then they will be the same.

        The second argument, if present, is the name of the environment
        variable whose value is required.  In the first example below, the
        PATH variable from the "parent" environment is specified, and its
        value will be assigned to %X.  In the second example, the PATH
        variable from the "child" environment is specified, and its value
        will be assigned to %Y.

        %X = ENVGET P PATH     ' RESULT: %P = C:\;C:\DOS;C:\UTILITY
                               ' OR SOMETHING SIMILAR TO THE ABOVE

        %Y = ENVGET C PATH     ' RESULT: %P = C:\;C:\DOS;C:\UTILITY
                               ' OR SOMETHING SIMILAR TO THE ABOVE






          COPYWRITE 1992 - 1994 ALL RIGHTS RESERVED, FELIX JAMES   PAGE 23
        
        BAX INTERPRETER VER 2.1 FOR DOS, STATEMENTS & FUNCTIONS    PAGE 24

        If the name of an environment variable is not specified as a
        second argument, then all the environment variables from either
        the parent or child group will be assigned to the special variables
        %A1 through %Axx, where "xx" is the number required to hold all
        the variables in the specified group.  For example, if the specified
        environment contains 12 variables, then they would be assigned to
        the BAX variables %A1 thru %A12.  If the specified environment
        contains more than 20 variables, additional %Axx variables will be
        created to accomodate them.  Example:

        %J = ENVGET P           ' RESULT: %J = NUMBER OF ENVIRONMENT VARS

        In this case, the return code from the ENVGET function will be the
        number of environment variables found.  The strings assigned to
        %A1 thru %Axx will be in the form:

        VARNAME=VALUE

        Both the environment variable name and the value assigned to it
        are contained in the same BAX variable, delimited from each other
        by an equal sign.  They can be easily separated with the following
        statement sequence or something equivalent.

        %L  = LOC %A1 =         ' FIND EQUAL SIGN
        %L  = ADD %L 1          ' POINT ONE CHAR PAST IT
        %EV = MID %A1 %L        ' SUBSTRING OFF VALUE
        %L  = SUB %L 2          ' POINT TO LAST CHAR IN NAME
        %EN = LEFT %A1 %L       ' EXTRACT NAME FROM FRONT OF %A1

        There are a number of BAX programs on the distribution disk which
        demonstrate the use of ENVGET.  (ANYVAR , ENVED , PATHEDIT , just
        to name a few.)

        Also see the ENVSET statement and the ENVSIZE function.























          COPYWRITE 1992 - 1994 ALL RIGHTS RESERVED, FELIX JAMES   PAGE 24
        
        BAX INTERPRETER VER 2.1 FOR DOS, STATEMENTS & FUNCTIONS    PAGE 25

                                 ENVSET STATEMENT

        The ENVSET statement allows you to change either the parent
        environment (usually DOS) or the child environment (your own).

        The ENVSET statement requires three values.  The first is the
        letter "P" or the letter "C" to indicate whether you intend to
        change the parent or child environment.  The second value is the
        name of the environment variable to be changed, and the third is
        the value to be assigned to the environment variable specified as
        item two.   Examples:

        ENVSET P MYVAR ABCDEFG      ' CHANGE PARENT ENVIRONMENT VARIABLE
                                    ' MYVAR TO 'ABCDEFG'.

        ENVSET C PATH  C:\;C:\DOS  ' CHANGE CHILD ENVIRONMENT VARIABLE
                                   ' PATH TO C:\;C:\DOS

        Most programs' environments are more difficult to change than
        COMMAND.COM'S is.  The reason for this, is that when first created,
        they only contain enough space for those variables which already
        exist.  You cannot add new variables or make the length of existing
        variables longer than they already are without first deleting one or
        more existing variables to make room for new or longer ones.  It can
        be done this way but ----- there is a simpler and better way.  See
        the ENVSIZE function.  Also see the ENVGET function.

                                  ENVSIZE FUNCTION

        The ENVSIZE function enables a BAX program to determine its
        environment size and also to increase it.  Examples:

        %S = ENVSIZE 0      ' RESULT: %S WILL EQUAL THE CURRENT ENV SIZE
        %I = ENVSIZE 512    ' RESULT: ENV SIZE WILL INCREASE BY 512 BYTES

        In the first example, the current size is returned in %S, but the
        environment space is not increased.

        In the second example, 512 bytes are added to the current space.
        Actually, it is likely that you will get an additional 16 bytes
        of space that you did not ask for, since the DOS service invoked
        to accomplish this, operates in terms of 16 byte blocks and
        always goes to the next even 16 byte boundary.  Another DOS
        quirk, but in this case a benign one.

        The minimum increase is 256 bytes, the maximum is 16384 bytes.

        If no  argument is supplied, a value of 0 is assumed.
        If the argument is negative, a value of 0 is assumed.

        If the value entered as an argument is greater than 0 but less than
        256, 256 is assumed.





          COPYWRITE 1992 - 1994 ALL RIGHTS RESERVED, FELIX JAMES   PAGE 25
        
        BAX INTERPRETER VER 2.1 FOR DOS, STATEMENTS & FUNCTIONS    PAGE 26

        If the value entered as an argument is greater than 16384, 16384 is
        assumed.

        You may test the size (arg=0) as many times as you like, but you
        may only increase the environment size once in any given execution
        of a program.

        Also see the ENVGET function and the ENVSET statement.

                                  EXECOM FUNCTION

        The EXECOM function executes a program which has either an EXE
        or COM extension.  Unlike the similar DOS function, it will not
        execute an internal COMMAND.COM command such as COPY, nor will
        it execute a BAT file.  Like the DOS function, it does retrieve
        the return code (ERRORLEVEL) from the executed program.  The
        DOS service which is called by EXECOM requires a full path and
        extension for the file which is to be executed.  It does not
        use the DOS path variable.  So why use EXECOM instead of DOS?

        For starters, EXECOM is faster and it uses less memory.  The DOS
        function actually calls COMMAND.COM, thereby creating a second
        DOS environment.  COMMAND.COM then executes the program for us.

        EXECOM removes the "middle man", COMMAND.COM.  This enables our BAX
        program to be a direct parent of the called program, which in turn
        means that the called program can not only pass a return code back
        to us, but that the called program can modify our environment since
        we are the parent, not COMMAND.COM.  This gives us the capability of
        returning character string values in addition to the standard
        "error-level", single value (0-255) return code.

        Examples:

        %RETCODE = EXECOM C:\UTIL\MYPROG.EXE DOGS PONIES
        %ANYCODE = EXECOM C:\ABCD\MYMENU.COM VANILLA ICE CREAM

        There is one quirk here worth mentioning.  Some programs require
        that their argument list begin with a blank.  If you are having
        problems getting a program to run properly, try inserting a
        blank as argument 1.  Example:

        %XYZ = EXECOM C:\WEIRD\BIRDS.COM %B PENGUINS PIGEONS DOVES

        See the sample program XCALLS.BAT on the distribution disk for
        some examples.











          COPYWRITE 1992 - 1994 ALL RIGHTS RESERVED, FELIX JAMES   PAGE 26
        
        BAX INTERPRETER VER 2.1 FOR DOS, STATEMENTS & FUNCTIONS    PAGE 27

                                  EXIST FUNCTION

        The EXIST function checks to see if a file exists.
        The filespec must be supplied as an argument. (Wild cards are ok)

        %TESTFILE = EXIST MYFILE.TXT       ' FILE IN CURRENT DIRECTORY
        %TESTFILE = EXIST C:\AUTOEXEC.BAT  ' FILE IN C DRIVE ROOT DIRECTORY

        Return code = 0 means that the file exists
        Return code = 1 means that the filespec contained an invalid path
        Return code = 2 means path ok, but the file did not exist

                     FILELIST STATEMENT AND FILENAME FUNCTION

        The FILELIST statement creates a list of filenames which can be
        returned, one at a time, to subseqent calls of the FILENAME
        function.  When the FILELIST statement is first called, it must
        specify a file mask.  For example, the statement:

                               FILELIST *.*

        will create a list of all the file names in the current directory.
        Once this has been done, any calls to the FILENAME function will
        result in the first or next file name in the list being assigned to
        the variable specified on the left side of the equal sign in the
        assignment statement which contains the FILENAME function.

        A list of directory names will be created if the keyword "DIR" is
        specified after the file mask.  Example:

                               FILELIST *.* DIR

        If the FILELIST statement is executed with no file name mask
        specified, then the memory occupied by the list of file names is
        released for other use.  It is a good idea to do this, once you are
        through using the file name list, especially if you are working in a
        directory which has a lot of files.

        Each time the FILENAME function is called, it returns a file name
        from the list created by the FILELIST statement.  When there are no
        file names left in the list, it returns a null string.  The FILENAME
        function does not require any arguments.

        Here is a small program which simply displays the file names in
        the current directory.












          COPYWRITE 1992 - 1994 ALL RIGHTS RESERVED, FELIX JAMES   PAGE 27
        
        BAX INTERPRETER VER 2.1 FOR DOS, STATEMENTS & FUNCTIONS    PAGE 28

        @ECHO OFF
        BAX %0 %1 %2 %3 %4 %5 %6 %7 %8 %9
        GOTO SKIPBAX
        =DIRDEMO
        FILELIST *.*                    'CREATE LIST OF FILENAMES
        LOOP =NOMORE                    'TOP OF LOOP TO DISPLAY THEM
        %F = FILENAME                   'GET A FILENAME
        IF %F = %N THEN LEAVE =NOMORE   'NULL STRING MEANS NO MORE OF THEM
        OUTPUT %F                       'DISPLAY FILE NAME ON SCREEN
        =NOMORE                         'BOTTOM OF LOOP
        FILELIST                        'RELEASE MEMORY OCCUPIED BY LIST
        END                             'END BAX PROGRAM
        :SKIPBAX

        Actually, it was not necessary to do the memory release in this
        program because BAX was terminating on the next statement anyway.
        The memory release is done for you automatically if you actually
        process all the files and the FILENAME function returns a null
        string.  If however, you terminated the loop based on some other
        condition beside the fact that FILENAME returned a null string,
        the memory would still be "tied up" and unavailable for some
        other process which might be able to make good use of it.  If you
        are not sure, it can't hurt to release the memory yourself.

        You can also supply a path with the file name mask.  For example,
        the following statement would create a list of all "EXE" files in
        the DOS directory of drive C.

                               FILELIST C:\DOS\*.EXE

        There are a number of programs which use the FILELIST statement and
        the FILENAME function on the BAX distribution disk.  They are
        liberally sprinkled with comments and documentation boxes.  If you
        study them, you will have little trouble with this facility.

                                FILEDATA FUNCTION

        The FILEDATA function returns directory information for a specific
        file.  Eight items of information are returned.

        1 -- Year         4 -- Hours          7 -- Size
        2 -- Month        5 -- Minutes        8 -- Attribute
        3 -- Day          6 -- Seconds

        Each item in the return string is delimited from the one following
        it with a single blank.  Example:

        %F = FDATA MYFILE.TXT 'RESULT: %F = 1992 06 18 14 09 22 00018922 32









          COPYWRITE 1992 - 1994 ALL RIGHTS RESERVED, FELIX JAMES   PAGE 28
        
        BAX INTERPRETER VER 2.1 FOR DOS, STATEMENTS & FUNCTIONS    PAGE 29

        Item 4 (hours) is military style 24 hour clock time.  Item 8,
        the value of the attribute byte, requires a little research to
        interpret properly.  Typically, you will see 0 or 32 in this field.
        A value of 0 means that the file does not have the archive bit set,
        while a value of 32 means that it does.  You normally don't have
        to worry about it, but for a complete description, see the help
        file for the DIRX program which is distributed as part of the
        BAX package.  Also see the ATTRIB command in your DOS manual.

        Item 7 (size), is always 8 characters, padded with leading zeros.

                                  GOTO STATEMENT

        The GOTO statement transfers control to the statement which begins
        with the label following the keyword GOTO.  The GOTO statement is
        often used as one or both clauses of the IF statement. Examples:

        GOTO =STOP
        IF %X = 0 THEN GOTO =SOMEWHERE ELSE GOTO =ELSEWHERE


                                   IF STATEMENT

        The IF statement tests to see if a condition is true or false and
        then takes one of two courses of action: one course for true, the
        other for false.

        IF %X = %Y THEN %V = 2 ELSE %V = 8

        In the above statement, the value represented by %X is tested
        against the value represented by %Y.  If the two values are equal,
        then the result of the test is true, so the statement following
        the keyword THEN is executed, but the statement following the
        keyword ELSE is not.  If the values tested were found not to be
        equal, then the statement following the keyword ELSE would be
        executed, but the statement following the keyword THEN would not.

        Any of the following comparison operators may be used to specify
        the test to be made.

        |<--OPERATOR-->|        MEANING

        =                       EQUAL
        <                       LESS THAN
        >                       GREATER THAN
        <>    (or)    ><        NOT EQUAL
        <=    (or)    =<        LESS THAN OR EQUAL
        >=    (or)    =>        GREATER THAN OR EQUAL









          COPYWRITE 1992 - 1994 ALL RIGHTS RESERVED, FELIX JAMES   PAGE 29
        
        BAX INTERPRETER VER 2.1 FOR DOS, STATEMENTS & FUNCTIONS    PAGE 30

        The THEN clause of the statement must always be present, but the
        ELSE clause is optional.  If the IF statement has no ELSE clause,
        then a false result from the test will simply transfer control
        to the statement following the IF statement.  The THEN clause
        will not be executed.  A few more examples:

        IF %J > 55 THEN GOTO =NOMORE
        IF %J = 10 THEN GOTO =LABEL01  ELSE GOTO =LABEL05
        IF %J = AB THEN %C = ABCDEFGHI ELSE OUTPUT SOMETHING IS WRONG

        Any statements can be specified in the THEN and ELSE clauses of
        an IF statement except IF, WHEN and LOOP.

                                  INPUT STATEMENT

        The INPUT statement is used to get a line of keyboard input.

        CURSORVH 0 1                        ' PUT CURSOR IN COLUMN 1
        OUTMSG ENTER NAME OF INPUT FILE --> ' DISPLAY PROMPT MSG
        %STUFF = RPT 40 %B                  ' ALLOCATE SPACE FOR NEW VALUE
        INPUT %STUFF                        ' GET USER'S INPUT

        The characters entered from the keyboard are assigned to the
        variable specified (%STUFF in the example).  Typically, you would
        want to display a message describing the type of input required.  In
        the example, the message is displayed with the OUTMSG statement.

        If the variable which is to receive the incoming string of
        characters from the keyboard already has a value assigned to it,
        then the existing value will be displayed and can be edited using
        the standard editing keys.  If you want a complete re-assignment of
        the variable as a result of the keyboard input, then initialize the
        variable to an appropriate number of blanks.  The number of blanks
        represents the maximum number of characters which the variable's
        new value can be.  This can be up to 80 characters provided that
        the input field begins in column 1.  The actual maximum length
        is the number of characters left on the line, starting with the
        current cursor position.  In the above example, a length of 40
        characters was used, but we could have calculated an exact
        maximum if we had done this:

        CURSORVH 0 1                        ' PUT CURSOR IN COLUMN 1
        OUTMSG ENTER NAME OF INPUT FILE --> ' DISPLAY PROMPT MSG
        %HPC  = CURSORH                     ' HORIZONTAL POSITION OF CURSOR
        %TEMP = SUB 80 %HPC                 ' SUBTRACT FROM SCREEN WIDTH
        %MAXLEN = ADD %TEMP 1               ' PLUS ONE = MAX POSSIBLE LENGTH
        %STUFF = RPT %MAXLEN %B             ' ALLOCATE SPACE FOR NEW VALUE
        INPUT %STUFF                        ' GET USER'S INPUT









          COPYWRITE 1992 - 1994 ALL RIGHTS RESERVED, FELIX JAMES   PAGE 30
        
        BAX INTERPRETER VER 2.1 FOR DOS, STATEMENTS & FUNCTIONS    PAGE 31

        The OUTMSG statement always leaves the cursor one position beyond
        the end of the message that it has just displayed.  It does not
        return the cursor to the left margin.

        Another approach is to make the initial value of the input variable
        a null string.  If you do this, BAX will calculate the maximum
        input field length for you and assign the input variable the
        appropriate number of blanks.

        The input field always begins at the current cursor position and
        will not "wrap around" to the next line.  Cursor movement is
        confined within the input field on the current line.

        If the specified variable already has a value, then the new value
        assigned to it cannot exceed its current length.  If you want to be
        able to add characters to the old value (make it longer), then you
        must "pad" it to the desired maximum length.  Typically you would
        do this with blanks, although any characters may be used.

        After typing whatever needs to be typed, the program user signals
        that he/she is done by pressing either the enter key or the escape
        key.  The special variable %EOI will be set to zero if the user
        pressed the enter key, or one if the user pressed the escape key.
        You can then test this value to determine how input was terminated.

        The user can perform editing on the input line with the following
        keys.

        Left arrow     Moves the cursor left
        Right arrow    Moves the cursor right
        Home           Moves the cursor to the beginning of the input field
        End            Moves the cursor to the end of the input field
        Insert         Toggles insert mode on / off
        Delete         Deletes the character at the cursor position
        Backspace      Same as Delete

        When insert mode is on, the cursor becomes a block about a half a
        character high.  If you toggle insert mode off, the cursor resumes
        its normal underscore appearance.

        There are several files on the distribution disk which use the
        INPUT statement.  In particular look at the ones named INPUT1,
        INPUT2, etc.  The INPUT statement is also used in all the various
        environment editors such as PATHEDIT, ENVED, ANYVAR, etc.

                                  INPUTF STATEMENT

        The INPUTF statement reads a line of input from the input file
        specified by the last OPENIN statement.  The maximum string length
        which can be read is 128 characters.

        INPUTF %DATA         'READ A LINE OF INPUT FROM THE INPUT FILE





          COPYWRITE 1992 - 1994 ALL RIGHTS RESERVED, FELIX JAMES   PAGE 31
        
        BAX INTERPRETER VER 2.1 FOR DOS, STATEMENTS & FUNCTIONS    PAGE 32

                                  INPUTK FUNCTION

        The INPUTK function accepts a single keystroke from the keyboard
        and assigns the ASCII value of the key pressed to a variable.

        %K = INPUTK          ' IF USER PRESSES THE SPACEBAR, %K = 32

        If the key pressed is not an ASCII character, a value of 0 is
        returned. (not all keys generate ASCII characters)

                                   JOIN FUNCTION

        The JOIN function joins (concatenates) its arguments into a single
        string.  Any number of arguments may be specified.

        %BIGONE = JOIN ABC X 12 XYZ        ' RESULT: %BIGONE = ABCX12XYZ
        %LILONE = **
        %BIGONE = JOIN %BIGONE %LILONE     ' RESULT: %BIGONE = ABCX12XYZ**

                                  LABGET FUNCTION

        The LABGET function returns the label of the specified drive. If no
        drive is specified, the label of the current drive is returned.

        %L = LABGET C        ' VOLUME LABEL FOR DRIVE C ASSIGNED TO %L

                                  LCASE FUNCTION

        The LCASE function translates a string of characters to lower case.

        %X = ABC*xyz         ' Mixed Case String
        %X = LCASE %X        ' RESULT: %X = abc*xyz

        Note: Also see UCASE function.

                                  LEAVE STATEMENT

        The LEAVE statement terminates execution of a loop which was
        initiated with the LOOP statement.  The LEAVE statement is the
        only correct way to exit from a loop.  It is possible to branch
        out of a loop with the GOTO statement, but this is not a good way
        to do it.  If you do this, BAX's internal control tables will not
        be updated and if you try to re-execute the loop at a later time
        you will get a nasty message saying that you have a loop structure
        error.  Here is a loop using the LEAVE statement to exit from it.

        %C = 0
        LOOP =XXX
        %C = ADD %C 1
        IF %C > 5 THEN LEAVE =XXX ELSE OUTPUT THIS IS ITERATION %C
        =XXX
        '******* CONTROL PASSES TO THIS LINE WHEN LEAVE IS EXECUTED ******

        The LEAVE statement is a defacto GOTO to the statement following
        the loop label.  Read the section on LOOP for more details.


          COPYWRITE 1992 - 1994 ALL RIGHTS RESERVED, FELIX JAMES   PAGE 32
        
        BAX INTERPRETER VER 2.1 FOR DOS, STATEMENTS & FUNCTIONS    PAGE 33

                                   LEFT FUNCTION

        The LEFT function extracts a substring from the left side of
        another string.  It requires two arguments:

        1) The string from which the substring is to be extracted.
        2) The number of characters to be extracted.

        %V = LEFT ABCDEFGH 4             ' RESULT: %V = ABCD
        %V = LEFT ABCDEFGH 14            ' RESULT: %V = ABCDEFGHbbbbbb

        where the lower case "b"s indicate blanks which were padded on the
        right side of the result to make the result the specified length.

        Note: Also see RIGHT and MID functions.

                                 LEN FUNCTION

        The LEN function returns the length of a string.

        %L = LEN ABCDEFG                    ' RESULT: %L = 7
        %J = ELEPHANT
        %L = LEN %J                         ' RESULT: %L = 8

                                    LIT FUNCTION

        The LIT function allows you to assign values which contain imbedded
        blanks to variables.  It can also be handy for assigning values
        which might otherwise be interpreted by BAX to mean something else.
        Examples would be words which start with per cent signs, or words
        which are BAX keywords.  Examples:

        %X = %XXX             'BAX WOULD CONSIDER %XXX A VARIABLE
        %X = LIT %XXX         '%X WILL BE ASSIGNED THE VALUE '%XXX'

        %X = ABC XYZ 123      '%X WILL BE ASSIGNED THE VALUE 'ABC'
        %X = LIT ABC XYZ 123  '%X WILL BE ASSIGNED THE VALUE 'ABC XYZ 123'

        %X = RIGHT            'BAX WOULD CONSIDER THIS A FUNCTION CALL
        %X = LIT RIGHT        '%X WILL BE ASSIGNED THE VALUE 'RIGHT'

        The LIT function is not totally literal, because it will not allow
        you to assign values with trailing blanks, and the comment character
        will still be considered a comment character.













          COPYWRITE 1992 - 1994 ALL RIGHTS RESERVED, FELIX JAMES   PAGE 33
        
        BAX INTERPRETER VER 2.1 FOR DOS, STATEMENTS & FUNCTIONS    PAGE 34

                                   LOC FUNCTION

        The LOC function locates a substring within a larger string.

        %I = LOC ABCDEFG D         ' RESULT: %I = 4
        %I = LOC ABCDEFG WET       ' RESULT: %I = 0    (NOT FOUND)

        You can optionally include a third argument which represents the
        character position where the search is to begin.

        %I = LOC ABCDABCD C 4      ' RESULT: %I = 7
        %I = LOC ABCDABCD A 6      ' RESULT: %I = 0  (NOT FOUND)
        %I = LOC ABCDABCD C 0      ' RESULT: %I = 7  (SEARCH BACKWARDS)

        If the third argument is zero, then the search is made backwards
        from the end of the string.  If the third argument is greater than
        the length of the string, zero is returned.

                                  LOOP STATEMENT

        The LOOP statement defines a loop.  All that is required after
        the keyword LOOP, is a label which is the location of the bottom
        of the loop.  Here is an example:

        %C = 0                          'INITIALIZE COUNTER
        LOOP =ABC                       'TOP OF LOOP
        %C = ADD %C 1                   'INCREMENT COUNTER BY 1
        IF %C > 20 THEN LEAVE =ABC      'TEST FOR LIMIT, BREAK LOOP
        %R = REM %C 2                   'DIVIDE AND ASSIGN REMAINDER
        IF %R > 0 THEN GOTO =ABC        'IF ODD NUMBER, ITERATE LOOP
        OUTPUT **********************
        OUTPUT
        OUTPUT %C IS AN EVEN NUMBER     'DISPLAY EVEN NUMBERS ONLY
        OUTPUT
        OUTPUT **********************
        =ABC                            'BOTTOM OF LOOP
        '****** LEAVE TRANSFERS CONTROL TO THIS LINE *********

        Always exit from loops with the LEAVE statement.  If you use GOTO
        to exit from a loop, BAX's internal control tables do not get
        updated and eventually you will get a loop structure error message.
        It is ok to use GOTO within the loop.  This was done in the above
        example.  Transferring control to the loop label at the bottom of
        the loop causes control to actually pass back to the statement
        following the LOOP statement itself.

        There must be at least one statement between the LOOP statement
        and the loop label.  If you actually do have only one intervening
        statement, think carefully about what it ought to be.

        It is ok to use the CALL statement to call subroutines which are
        outside the loop, because when the RETURN statement is executed,
        control returns back inside the loop.  In the context of subroutine
        calls, we have not actually left the loop, even though statements
        physically located outside the loop are being executed.


          COPYWRITE 1992 - 1994 ALL RIGHTS RESERVED, FELIX JAMES   PAGE 34
        
        BAX INTERPRETER VER 2.1 FOR DOS, STATEMENTS & FUNCTIONS    PAGE 35

        Loops can be nested to any level, but make sure that they are in
        fact nested, and are not overlapping each other.  In other words,
        each inner loop's LOOP statement and loop label must both lie
        inside the outer loop's LOOP statement and loop label.

        CORRECT (NESTED)                      INCORRECT (OVERLAPPING)

        LOOP =AAA                             LOOP =AAA
        .....                                 .....
             LOOP =BBB                            LOOP =BBB
            ..........                            .....
            =BBB                              =AAA
        .....                                 .....
        =AAA                                            =BBB

        See the LEAVE statement for some additional information.

                                  MEMORY FUNCTION

        The MEMORY function returns a string containing three numbers.

        1: The total amount of memory (in bytes) currently available
        2: The maximum number of variables available to your BAX program
        3: The number of variables which your BAX program has used

        Example:     %X = MEMORY
                     OUTPUT %X

        A typical display after executing the above statements would be:

        25332 256 36

        If you write fairly small programs (up to 200 lines) and you never
        increase your variable table size, you will probably have no use for
        this function.  If however, you are writing large programs of say,
        500 lines or more, and you are increasing your variable table to
        500+, this function will give you a handle on how much memory your
        program is using and give you some warning that your program is
        about to crash.  Watch the total amount of memory carefully if you
        are writing large programs.  BAX does some checking and will
        terminate with error code 107 if available memory falls below about
        1000 bytes.  Using the 1000 byte "pad" allows BAX to terminate in a
        clean and orderly manner without your having to re-boot your system.
        Things get pretty unpredictable when the available memory actually
        reaches zero.  This is a condition that is best avoided.

        While it is generally true that a large program with many statements
        and many variables will use more memory than a smaller program,
        it is possible for a small program to run out of memory.  The
        program, EATMEM.BAT, on the BAX distribution disk is an example
        of a program which, though modest in size, will run out of memory.






          COPYWRITE 1992 - 1994 ALL RIGHTS RESERVED, FELIX JAMES   PAGE 35
        
        BAX INTERPRETER VER 2.1 FOR DOS, STATEMENTS & FUNCTIONS    PAGE 36

                               MID FUNCTION

        The MID function extracts a substring from another string.
        It requires two or three arguments:

        1)  The string from which the substring is to be extracted.
        2)  The beginning character position of the string to be extracted.
        3)  The length of the string to be extracted. (Optional, see below)

        %V = MID ABCDEFGH 4 3      ' RESULT:  %V = DEF
        %Z = MID ABCDEFGH 4 88     ' RESULT:  %Z = DEFGH
        %J = MID ABCDEFGH 4        ' RESULT:  %J = DEFGH
        %S = TUVWXYZ
        %M = 2
        %L = 5
        %S = MID %S %M %L          ' RESULT:  %S = UVWXY

        If the length specified would make the substring extend beyond the
        end of the original string, then all remaining characters in the
        original string are returned.  If this is what you want, you can
        specify a big number for the length, or simply omit it, as has been
        done in the third example.

        Note: Also see LEFT and RIGHT functions.

                                  MONITOR FUNCTION

        The MONITOR function provides a simple way to tell if your program
        is running on a monochrome or color monitor.  It returns a value of
        0 if you are running on a monochrome monitor or a value of 1 if you
        are running on a color monitor.  Example:

        %MON = MONITOR     'RESULT: %MON = 0 IF MONOCHROME, OR 1 IF COLOR

        Knowing the type of monitor can be handy if you write programs
        which should be able to run on either type, because then you
        can conditionally execute the COLORS statement.  While most
        monochrome monitors are not adversely affected by most COLORS
        settings, there are some which are.  Settings like gray on black
        often don't show up well on monochrome monitors.

















          COPYWRITE 1992 - 1994 ALL RIGHTS RESERVED, FELIX JAMES   PAGE 36
        
        BAX INTERPRETER VER 2.1 FOR DOS, STATEMENTS & FUNCTIONS    PAGE 37

                                  MOVE STATEMENT

        The MOVE statement moves a file from one directory to another, or
        it can be used to simply rename a file.  It cannot be used to move
        files from one drive to another.  It requires two arguments.  The
        first argument is the filespec of a file to be moved or renamed.
        The second argument is the new filespec of the file for which the
        move operation is being done.  Both filespecs may contain DOS
        paths, but DOS wildcard characters are not allowed.

        MOVE MYFILE.TXT MYFILE.DAT            'SIMPLE RENAME
        MOVE MYFILE.TXT C:\UTILITY\MYFILE.TXT 'MOVE TO ANOTHER DIRECTORY

        MOVE C:\MYDIR\MYFILE.TXT C:\UTILITY\MYFILE.TXT 'PATHS ON BOTH FILES

        %X = C:\MYDIR\MYFILE.TXT   'NAME OF FILE AS IT CURRENTLY EXISTS
        %Y = C:\UTILITY\MYFILE.TXT 'NAME OF FILE AT DESTINATION
        MOVE %X %Y                 'VARIABLES USED INSTEAD OF CONSTANTS

        The first file must exist, the second one must not, at the time
        that the statement is executed.

                                  NOW FUNCTION

        The NOW function returns the system date and time.  A single blank
        is inserted between each of the six values which are:


        ITEM#      1       2       3      4        5         6
        ITEM     year    month    day    hour    minute    second
        CHARS    1-4     6-7      9-10   12-13   15-16     18-19

        %X = NOW   'RESULT: %X = 1993 03 24 18 23 09      (MAYBE)

        The single blank delimiter between each item enables you to
        easily extract the individual items with the PARSE function.

        Since each item is placed in specific character positions, you
        may also extract individual items with the LEFT, MID and
        RIGHT functions.

        The year - month - day - hour - minute - second sequence is
        the simplest one for testing and sequencing files by their
        creation or last update time.

        The time is military style 24 hour clock time.  Midnight is
        00 00 00 while noon is 12 00 00.  One o'clock in the afternoon
        is 13 00 00 , etc.









          COPYWRITE 1992 - 1994 ALL RIGHTS RESERVED, FELIX JAMES   PAGE 37
        
        BAX INTERPRETER VER 2.1 FOR DOS, STATEMENTS & FUNCTIONS    PAGE 38

        NOTE: BAX does not provide specific functions to change date and
        time, since the DOS commands which provide this service are very
        easy to use.  If you wish to change DATE or TIME from a BAX program,
        simply issue CMD statements.  Examples:

        CMD DATE 02-22-93          (or)      CMD TIME 12:24:33p

        The format of the DOS date and time can vary from system to
        system, so check your DOS manual for specific details.

                                   NUM FUNCTION

        The NUM function determines if a string can be converted to a
        numeric integral value.  If it can, it returns the value 0,
        otherwise it returns 1. Range = -2,147,483,648 thru 2,147,483,647

        %TEST = NUM 467          ' RESULT: %TEST = 0
        %TEST = NUM ABCDEFG      ' RESULT: %TEST = 1  (CONTAINS ALPHAS)
        %TEST = NUM 5.3          ' RESULT: %TEST = 1  (INTEGERS ONLY)
        %TEST = NUM -29          ' RESULT: %TEST = 0

        %J = 123
        %TEST = NUM %J           ' RESULT: %TEST = 0

                        OPENIN AND OPENOUT STATEMENTS

        These statements are the file open statements.  They specify what
        type of processing is to be done on the specific file which appears
        in the statements.  BAX allows a maximum of two files to be
        open at any given time:  one input file, and one output file.

        OPENIN  MYFILE.TXT     ' OPEN STATEMENT USING CONSTANT
        OPENOUT MYFILE.%X      ' OPEN STATEMENT USING HYBRID
        OPENOUT %FNAME         ' OPEN STATEMENT USING VARIABLE

        Let's look at the only really tricky thing we have to know to
        successfully read a file. That is, how do we know when we don't
        have any more data to read.  BAX will tell you when this happens
        by setting the %EOF variable, which normally has a value of 0,
        to a value of 1.  Let's go through one simple example of how to
        test for the %EOF variable.  This is a place where many beginning
        programmers (and even experienced ones) sometimes have trouble.

        Suppose we have a file called MYFILE.TXT which contains four
        records as follows:

        THIS IS RECORD #1
        THIS IS RECORD #2
        THIS IS RECORD #3
        THIS IS RECORD #4







          COPYWRITE 1992 - 1994 ALL RIGHTS RESERVED, FELIX JAMES   PAGE 38
        
        BAX INTERPRETER VER 2.1 FOR DOS, STATEMENTS & FUNCTIONS    PAGE 39

        We want to read the records from this file and display them on
        the screen, so we write the following program. Let's call our
        program "READIT.BAT".

        @ECHO OFF
        BAX %0 %1 %2 %3 %4 %5 %6 %7 %8 %9
        GOTO SKIPBAX
        =READIT                           'START OF BAX PROGRAM
        OPENIN %A1                        'FILESPEC IS FIRST ARGUMENT
        LOOP =AGAIN                       'TOP OF OUR I/O LOOP
        INPUTF %DATA                      'READ A RECORD FROM THE FILE
        IF %EOF > 0 THEN LEAVE =AGAIN     'TEST %EOF AFTER INPUTF
        OUTPUT VALUE FROM FILE IS: %DATA  'DISPLAY RECORD ON SCREEN
        =AGAIN                            'GO BACK AND DO ANOTHER ONE
        CLOSEIN                           'CLOSE THE FILE !! IMPORTANT !!
        END                               'END OF BAX PROGRAM
        :SKIPBAX

        If we execute this program from the DOS prompt with the command:

        READIT MYFILE.TXT

        The output display on the screen will be:

        VALUE FROM FILE IS: THIS IS RECORD #1
        VALUE FROM FILE IS: THIS IS RECORD #2
        VALUE FROM FILE IS: THIS IS RECORD #3
        VALUE FROM FILE IS: THIS IS RECORD #4

        Notice that we tested for the value of %EOF after the INPUTF
        statement, and not before it.  This is the proper way to do it
        in BAX programs.

        Note: Also see CLOSEIN , CLOSEOUT , INPUTF , OUTPUTF

                                OUTMSG STATEMENT

        The OUTMSG statement writes a line of output to the screen.  Each
        word specified is displayed with a single intervening blank.

        The OUTMSG statement starts displaying characters at the current
        cursor position on the current line.  It leaves the cursor at the
        character position following the last character it displayed.  It
        will never advance to the next line on the screen.  If the line
        to be displayed will not fit on the screen, it will be truncated
        and the cursor moved to column position one on the same line.

        The OUTMSG statement can therefore be used if your program is
        prompting the user to enter information which will be supplied in
        response to an INPUT statement.  Input can then be entered on the
        same line as the prompt message.  The same logic also applies, if
        you are getting a single keystroke from the INPUTK function.





          COPYWRITE 1992 - 1994 ALL RIGHTS RESERVED, FELIX JAMES   PAGE 39
        
        BAX INTERPRETER VER 2.1 FOR DOS, STATEMENTS & FUNCTIONS    PAGE 40

        CURSORVH 0 1                            ' PUT CURSOR IN COLUMN 1
        OUTMSG ENTER ANY KEY WHEN READY --->    ' DISPLAY MSG
        %K = INPUTK                             ' GET ONE KEYSTROKE

        The OUTMSG statement honors the current COLORS setting.

                                  OUTPUT STATEMENT

        The OUTPUT statement writes a line of output to the screen.  Each
        word specified is displayed with a single intervening blank.

        %X = 8
        OUTPUT THERE ARE %X WORDS DISPLAYED ON THIS LINE

        The OUTPUT statement always begins in column one of the
        current line and if the line to be displayed is more than 80
        characters wide, it will display the "overflow" on the next line.
        After all characters have been displayed, the cursor is moved to
        column one on the line following the one where the display ended.
        The screen will be scrolled one or two lines as required.

        It is usually a good idea to issue a "blank" OUTPUT statement after
        an INPUT statement, an OUTMSG statement or a statement which
        calls the INPUTK function so that the cursor line will move down
        and the screen will be scrolled if necessary.  This is not an
        "iron clad" rule, it all depends on what you are trying to do.
        Here is one simple example where it is probably a good idea:

        CURSORVH 0 1                            'PUT CURSOR IN COLUMN 1
        OUTMSG PRESS A KEY TO CONTINUE          'ISSUE A MSG, HOLDING CURSOR
        %X = INPUTK                             'WAIT FOR A KEY PRESS
        OUTPUT                                  'MOVE CURSOR DOWN ONE LINE
        OUTPUT THANK YOU. WE WILL NOW CONTINUE  'DISPLAY MSG WITH OUTPUT

        Without the blank OUTPUT statement on the fourth line, the message
        displayed by OUTMSG on the second line will be overwritten by the
        message displayed by OUTPUT on the fifth line.

        The OUTPUT statement honors the current COLORS setting.

                                 OUTPUTF STATEMENT

        The OUTPUTF statement writes a line of OUTPUT to the file specified
        in the last OPENOUT statement.  Each word specified is written on
        the file with a single intervening blank.  Each line of output
        represents one file record and is terminated with the standard
        carriage return - linefeed record separator.

        OUTPUTF %X %Y %Z             'WRITE THREE VALUES TO OUTPUT FILE
        OUTPUTF %WHOLELINE           'WRITES A SINGLE VALUE TO THE FILE

        Note: Also see OPENIN  , OPENOUT , INPUTF , CLOSEOUT





          COPYWRITE 1992 - 1994 ALL RIGHTS RESERVED, FELIX JAMES   PAGE 40
        
        BAX INTERPRETER VER 2.1 FOR DOS, STATEMENTS & FUNCTIONS    PAGE 41

                                 OVERLAY FUNCTION

        The OVERLAY function places characters from one string into
        another string at a particular character position.  Three
        arguments are required:

        1) The string which is to receive the overlay characters.
        2) The string which is to overlay the existing string.
        3) The character position at which the overlay will start.

        %M = ABCDEFGHIJKLMNOP
        %J = ___
        ' THIS COMMENT IS A SCALE                  12345678901234567890
        %M = OVERLAY %M %J 4        ' RESULT: %M = ABC___GHIJKLMNOP
        %Z = 12345
        %M = OVERLAY %M %Z 15       ' RESULT: %M = ABC___GHIJKLMN12345

        Notice that you can extend the length of a string this way, provided
        that the third argument (the starting position) is less than or
        equal to the length of the original string.

                                  PARSE FUNCTION

        The PARSE function breaks up a large string into smaller substrings
        which are delimited from each other by blanks.  It is used primarily
        after an INPUT or INPUTF statement which reads a line of input
        from the keyboard or from a file.  One argument is required:  the
        string to be parsed.  The following program segment shows the
        technique.

        OUTPUT ENTER A LINE OF INPUT     'DISPLAY MESSAGE ASKING FOR INPUT
        INPUT %STUFF                     'ASSIGN KEYBOARD INPUT TO %STUFF
        %X = PARSE %STUFF                'EXTRACT BLANK DELIMITED WORDS

               ASSUME KEYBOARD ENTRY WAS: ONE TWO THREE FOUR

        Now:  %STUFF = ONE TWO THREE FOUR
        and:     %A1 = ONE
                 %A2 = TWO
                 %A3 = THREE
                 %A4 = FOUR
                 %X  = 4   (the number of substrings extracted from %STUFF

        The PARSE function treats multiple delimiter characters as a single
        delimiter character, and ignores leading and trailing delimiter
        characters.











          COPYWRITE 1992 - 1994 ALL RIGHTS RESERVED, FELIX JAMES   PAGE 41
        
        BAX INTERPRETER VER 2.1 FOR DOS, STATEMENTS & FUNCTIONS    PAGE 42

        Notice that the variable names which contain the substrings are the
        same as those used to hold the arguments passed to your BAX program
        at execution time.  These variables (%A1 thru %A20), are the PARSE
        function's work area.  They are initialized to null strings each
        time PARSE is called, and then "back-filled" with the new values
        which PARSE extracts from the string specified as an argument.
        The values which %A1 thru %A20 contained before PARSE was called
        are lost, so if you need these values, assign them to other variables
        before calling PARSE.

                                 PATHFIND FUNCTION

        The PATHFIND function searches either the DOS path or any other path
        in the same format as the DOS path, for a specified filename.  The
        filename may not contain wild cards.  If no extension is specified,
        then the search performed is a search for the three standard
        executable file extensions:  COM EXE BAT.  If an extension is
        specified, then the search is performed for that specific file only.
        If you wish to search for a file with a null extension, then specify
        the file with an extension which consists of only the period.
        If the file is found, then the return value will be the complete
        filespec for the file.  If the file is not found, then a null string
        is returned.

        '                  EXAMPLE USING DOS PATH VARIABLE
        '
        %F = MYFILE.TXT               'NAME OF FILE WE ARE LOOKING FOR
        %P = ENVGET P PATH            'GET DOS PATH VARIABLE
        %FSPEC = PATHFIND %F %P       'SEARCH FOR FILE IN PATH DIRECTORIES
        '
        IF %FSPEC = %N THEN OUTPUT FILE NOT FOUND
        '                     CONTINUE WITH WHATEVER


        '                  EXAMPLE USING ANY PATH
        '
        %F = MYFILE.TXT                    'NAME OF FILE WE ARE LOOKING FOR
        %P = C:\;C:\MYLIB;C:\DOS;C:\GAMES  'PATH TO SEARCH
        %FSPEC = PATHFIND %F %P            'SEARCH FOR FILE IN PATH DIRS
        '
        IF %FSPEC = %N THEN OUTPUT FILE NOT FOUND
        '                     CONTINUE WITH WHATEVER

        In the above example, if the file had been found in the MYLIB
        directory, the value of %FSPEC would be: C:\MYLIB\MYFILE.TXT

        Any path may be used that is in the same format as the DOS path.
        This function may be used to search for files with any extensions.
        It is not limited to executables (COM, EXE, BAT).  It also enables
        you to set up alternate paths for different purposes without having
        to change and restore the value of the path variable in the DOS
        environment, or require that you have an inordinately long DOS
        path variable.




          COPYWRITE 1992 - 1994 ALL RIGHTS RESERVED, FELIX JAMES   PAGE 42
        
        BAX INTERPRETER VER 2.1 FOR DOS, STATEMENTS & FUNCTIONS    PAGE 43

                                   POS FUNCTION

        The POS function returns the position of a word in a list of words.
        The word to be searched for is the last one in the list.  All words
        up to the last one are tested against the last one and if a match is
        found, then the position in the list where the match was found is
        returned.  Zero is returned if no match is found.

        %I = POS DOGS CATS GOATS RATS CATS   ' RESULT: %I = 2
        %I = POS 10   20   30    40   15     ' RESULT: %I = 0  (NOT FOUND)

                                 REBOOT STATEMENT

        The REBOOT statement reboots your system.  It is functionally
        equivalent to pressing the cntrl-alt-del keys.  It is handy if you
        boot up with many different configurations of CONFIG.SYS and
        AUTOEXEC.BAT.  Your BAX program can do the appropriate copying
        or moving of files and then go ahead and reboot for you.

        REBOOT

                                  RIGHT FUNCTION

        The RIGHT function extracts a substring from the right side of
        another string.  It requires two arguments:

        1) The string from which the substring is to be extracted.
        2) The number of characters to be extracted.

        %V = RIGHT ABCDEFGH 3              ' RESULT: %V = FGH
        %V = RIGHT ABCDEFGH 12             ' RESULT: %V = bbbbABCDEFGH

        where the lower case "b"s indicate blanks which were padded on the
        left side of the result to make the result the specified length.

        Note: Also see LEFT and MID functions.

                                 RETURN STATEMENT

        The RETURN statement is used to terminate a subroutine and transfer
        control back to the statement following the CALL statement which
        called the subroutine.

        RETURN                ' RETURN CONTROL TO OUR CALLER

        See the CALL statement for additional information.











          COPYWRITE 1992 - 1994 ALL RIGHTS RESERVED, FELIX JAMES   PAGE 43
        
        BAX INTERPRETER VER 2.1 FOR DOS, STATEMENTS & FUNCTIONS    PAGE 44

                                   RPT FUNCTION

        The RPT function creates a string consisting of replications of a
        character which is specified as an argument.  One or two arguments
        are required.

        1) The number of times argument two is to be repeated.
        2) The character which is to be repeated.

        %S = RPT 8 A                ' RESULT: %S = AAAAAAAA
        %S = RPT 4                  ' RESULT: %S = bbbb (4 BLANKS)
        %S = RPT 0                  ' RESULT: %S = n (A NULL STRING)

        If the second argument is omitted, it is assumed to be a blank.  If
        the first argument is 0, a null string is returned no matter what
        the second argument is.

                                 STOP STATEMENT

        The STOP statement terminates execution of a BAX program.  It can
        appear anywhere in the program.

        STOP           ' ERROR LEVEL 0 RETURNED TO CALLER

        STOP 4         ' ERROR LEVEL 4 RETURNED TO CALLER

        STOP %BAD      ' VALUE OF VARIABLE %BAD RETURNED TO CALLER

        IF %X = 0 THEN %Y = 2 ELSE STOP %RETCODE

                                  SWAP STATEMENT

        The SWAP statement exchanges the values of two variables.

        %X = ABC
        %Y = XYZ
        SWAP %X %Y   ' RESULT: %X = XYZ   ,   %Y = ABC




















          COPYWRITE 1992 - 1994 ALL RIGHTS RESERVED, FELIX JAMES   PAGE 44
        
        BAX INTERPRETER VER 2.1 FOR DOS, STATEMENTS & FUNCTIONS    PAGE 45

                                   TEST FUNCTION

        The TEST function makes up to five tests and returns the results of
        the tests in a string consisting of zeros and ones.  If the test is
        false, then a zero is returned.  If the test is true, then a one is
        returned.  We can best see how this works with an example.

        %A1 = CAT
        %A2 = 5
        %X  = 17
        %Y  = 0
        %Z  = 7
        %T = TEST %A1 = DOG   %A2 > 5   %X <= 17   %Y <> 4   %Z = 7

        If the above program segment were executed, %T would equal 00111,
        because test1 was false, test2 was false, test3 was true, test4
        was true, and test5 was true.

        %J = 1
        %K = 5
        %T = TEST %J = 1  %K = 6

        If the above program segment were executed, %T would equal 10,
        because test1 was true and test2 was false.

        The comparison operators are the same as those used with the IF
        statement.  See the discussion of the IF statement for a complete
        list.

                                  TRANS FUNCTION

        The TRANS function requires three arguments.  It works like this.
        The first character is extracted from argument two.
        The first character is extracted from argument three.
        A search is made in argument one, to see if the character from
        argument two is present in argument one.
        If so, then the character in argument one is replaced by the
        character from argument three.  If the character occurs multiple
        times in argument one, it is replaced in all locations.

        This process is then repeated using character #2 from argument
        two and argument three, again using character #3, etc .... etc.
        Arguments two and three must be the same length.  If none of the
        characters from argument two are found in argument one, then
        argument one is the value returned.

        %X = ABCDEFGH                'WORKING STRING FOR DEMO
        %Y = TRANS %X ACH XYZ        'RESULT: %Y = XBYDEFGZ

        %X = 02-26-92                'ANOTHER DEMO
        %Y = TRANS %X - /            'RESULT: %Y = 02/26/92






          COPYWRITE 1992 - 1994 ALL RIGHTS RESERVED, FELIX JAMES   PAGE 45
        
        BAX INTERPRETER VER 2.1 FOR DOS, STATEMENTS & FUNCTIONS    PAGE 46

                          TRIM , TRIML , TRIMR FUNCTIONS

        These functions require a single argument which must be a variable,
        double variable or hybrid word.

        TRIM  removes both leading and trailing blanks from the argument.
        TRIML removes only leading blanks from the argument.
        TRIMR removes only trailing blanks from the argument.

        %X = TRIM  %V        ' REMOVE LEADING AND TRAILING BLANKS
        %Y = TRIML %J%K      ' REMOVE BLANKS FROM THE LEFT ONLY
        %Z = TRIMR ABC%J     ' REMOVE BLANKS FROM THE RIGHT ONLY

                                   UCASE FUNCTION

        The UCASE function converts lower case characters to upper case.

        %X = UCASE *AaBbCc12           ' RESULT: %X = *AABBCC12

        Non alphabetic characters are not affected. (Also see LCASE)

                                  VERIFY FUNCTION

        The VERIFY function takes each character from one string and tries
        to find a matching character in a second string.  If all characters
        from the first string are present in the second string, then the
        return code is zero.  If a character is not found in the second
        string, then the return code is the character position of the
        "orphan" character in the first string.  Let's look at examples.

        %V = VERIFY TAS SEATTLE   'RESULT: %V = 0  (ALL CHARACTERS FOUND)
        %V = VERIFY BAN BOSTON    'RESULT: %V = 2  (SECOND CHAR NOT FOUND)

        Notice that the sequence of the characters in either string is not
        significant, only their presence matters.

                                   WHEN STATEMENT

        The WHEN statement tests to see if a condition is true or false and
        then executes or does not execute a group of statements, depending
        on the result of the test.  The format of the WHEN statement is:

        WHEN value1 operator value2 label
                      (or)
        WHEN value1 operator value2 label1 label2

        The label(s) may not be represented by variables.

        Let's look at an example of the simple one label format first.








          COPYWRITE 1992 - 1994 ALL RIGHTS RESERVED, FELIX JAMES   PAGE 46
        
        BAX INTERPRETER VER 2.1 FOR DOS, STATEMENTS & FUNCTIONS    PAGE 47

        WHEN %OPFLAG = 0 =OPENFILE
        OPENIN MYFILE.TXT
        %OPFLAG = 1
        =OPENFILE

        In the above example, the two statements between the WHEN statement
        and the label =OPENFILE are executed only when the indicated test is
        true ( %OPFLAG = 0 ). If the value of the variable %OPFLAG is not
        zero, then the test result is false and the two statements are not
        executed.

        Any of the following comparison operators may be used to specify
        the test to be made.

        |<--OPERATOR-->|        MEANING

        =                       EQUAL
        <                       LESS THAN
        >                       GREATER THAN
        <>    (or)    ><        NOT EQUAL
        <=    (or)    =<        LESS THAN OR EQUAL
        >=    (or)    =>        GREATER THAN OR EQUAL

        Now let's look at an example of the two label format.

        WHEN %X = %Y =CATS =DOGS      'MAKE TEST AND SPECIFY LABELS
        '
        OUTPUT THE TEST WAS TRUE      'THESE THREE LINES ARE EXECUTED IF
        %J = 1                        'THE TEST WAS TRUE BUT THEY ARE NOT
        %K = ADD %JUNK %TRASH         'EXECUTED IF THE TEST WAS FALSE.
        '
        =CATS                         'THE DIVIDING LINE BETWEEN TRUE AND FAL E
        '
        OUTPUT THE TEST WAS FALSE     'THESE THREE LINES ARE EXECUTED IF
        %J = 2                        'THE TEST WAS FALSE BUT THEY ARE NOT
        %K = SUB %TRASH 4             'EXECUTED IF THE TEST WAS TRUE.
        '
        =DOGS                         'RESUME NORMAL PROGRAM FLOW HERE

        In the above example, the value represented by %X is tested
        against the value represented by %Y.  If the two values are equal,
        then the result of the test is true, so the statements between the
        WHEN statement and the label =CATS are executed, but the statements
        between the label =CATS and the label =DOGS are not executed.

        If the values represented by %X and %Y are not equal, then the
        result of the test is false and the range of statements between the
        WHEN statement and the label =CATS would not be executed, but the
        range of statements between the label =CATS and the label =DOGS
        would be executed.







          COPYWRITE 1992 - 1994 ALL RIGHTS RESERVED, FELIX JAMES   PAGE 47
        
        BAX INTERPRETER VER 2.1 FOR DOS, STATEMENTS & FUNCTIONS    PAGE 48

        In the following discussion, we will use the term WHENBLOCK.  A
        WHENBLOCK consists of the WHEN statement itself and includes all
        the program statements between the WHEN statement and the last
        label specified in the WHEN statement and the last label itself.

        The labels specified in a WHEN statement must follow the WHEN
        statement in the program and the second label must follow
        the first one.

        WHENBLOCKS can be nested to any level, but like LOOP statements,
        they must be nested, not over-lapped.  Results are unpredictable if
        a program has over-lapping WHENBLOCKS in it.

        WHENBLOCKS and loops may not overlap each other.  One must be
        completely nested inside the other.  Results are unpredictable if
        a program has overlapping loops and WHENBLOCKS in it.

        Each WHENBLOCK must have its own label or pair of labels.

        If WHENBLOCKS are nested inside loops or if loops are nested
        inside WHENBLOCKS, the WHENBLOCKS and loops must have
        their own labels.

        You can use the GOTO statement to transfer control out of a
        WHENBLOCK but results can be unpredictable if you try to transfer
        control back into an active WHENBLOCK with a GOTO statement.
        You can use GOTO within the WHENBLOCK itself as long as you do
        not use it to transfer control from the TRUE section to the FALSE
        section or from the FALSE section to the TRUE section of a two
        label WHENBLOCK.

        As a general rule, GOTO statements should be avoided when you are
        working with programming structures such as loops or logic blocks.
        This is true, not just when using BAX, but with just about all
        modern programming languages.  Some languages (REXX for example),
        don't even have a GOTO statement.

                                   WORD FUNCTION

        The WORD function returns a word which occupies a specific position
        in a list of words.  The position is specified with the last word
        in the statement which is of course not part of the list.

        %X = 3
        %Y = 6
        '           (1)   (2)  (3)    (4)    (5)
        %W = WORD BALLS BATS BASES UMPIRES BEER %X   ' RESULT: %W = BASES
        %W = WORD BALLS BATS BASES UMPIRES BEER %Y   ' RESULT: %W = n (null)

        If the position is less than one or greater than the number of items
        in the list, then a null string is returned (example 2 above).






          COPYWRITE 1992 - 1994 ALL RIGHTS RESERVED, FELIX JAMES   PAGE 48
        
        BAX INTERPRETER VER 2.1 FOR DOS, STATEMENTS & FUNCTIONS    PAGE 49

                                 WORKAREA FUNCTION

        The WORKAREA function gives your BAX program access to an additional
        block of memory which is independent of the memory where your
        program's statements and variables reside.  You may specify any size
        from 256 to 16384 bytes.  The size will be rounded up to the next
        256 byte boundary.  For example, if you specify 1000 you will get
        1024.  The default is 256.  Example:

        %WAS = 1024                    'WORK AREA SIZE IN BYTES
        %WAP = WORKAREA %WAS           'CREATE WORK AREA AND GET POINTER

        The value returned by the WORKAREA function is a pointer to the
        first byte of the work area assigned to your program.  This value
        can be used by your program to read and write data to your work area
        using the WORKGET function and the WORKSET statement.  If you pass
        this value to another program which you are calling as an external
        sub-routine, then that program can also read and write data to your
        work area.  This is an easy and convenient way to pass data to
        and from your external sub-routines.

        The first time that your program calls the WORKAREA function, it
        creates a work area for your program and initializes the area to all
        blanks.  If you call the WORKAREA function again in the same
        program, the only effect it will have is to re-initialize the area
        to all blanks.  Once the work area has been created, its size cannot
        be changed.  When your program terminates execution, the work area
        memory is released back into the DOS pool of free memory.

        The usual scenario for calling an external sub-routine and getting
        information back from it via the work area goes something like this.

        %WAPOINTER = WORKAREA 256  'CREATE WORK AREA AND GET POINTER TO IT
        CMD EXTPROG %WAPOINTER     'PASS THE POINTER TO THE PROGRAM 'EXTPROG'
        %RETDATA = WORKGET 1 128   'RETURNED DATA IS IN BYTES 1 THRU 128

        The external program (EXTPROG in this example) needs to know, at a
        bare minimum, the location where it is to write the data that it
        generates.  In actual practice, it probably needs some additional
        parameters so that it will know what to do.  It might also need to
        know where in the work area it is supposed to start writing.  In
        this simple example, EXTPROG is assuming that it is supposed to
        start writing at the first byte in the work area.  We can hardly
        blame him, we didn't tell him anything else.

        There are several programs on the distribution disk which show the
        technique in greater detail.  These programs are well documented
        and contain many examples of working code.









          COPYWRITE 1992 - 1994 ALL RIGHTS RESERVED, FELIX JAMES   PAGE 49
        
        BAX INTERPRETER VER 2.1 FOR DOS, STATEMENTS & FUNCTIONS    PAGE 50

                                  WORKGET FUNCTION

        The WORKGET function transfers one or more characters from the
        work area to a BAX variable.  Two or three arguments are required.

        Let's say the first 40 characters of a work area are as shown
        below.  The SCALE lines of course are not actually in the work area
        and are for reference only.

        SCALE (10'S)                1         2         3         4
        SCALE (UNITS)      1234567890123456789012345678901234567890

        WORKAREA CONTENTS: APPLES    PEARS     LEMONS    ORANGES

        %X = WORKGET 11 10   'RESULT: %X = PEARSbbbbb ("b"s represent blanks)

        %Y = WORKGET 26 6    'RESULT: %Y = SbbbbO

        %Z = WORKGET 21 6 %P 'RESULT: %Z = LEMONS (%P POINTS TO A WORK AREA)

        The first argument is the character position where the transfer is
        to begin.  The second argument is the number of characters to be
        transferred (max = 128).  The third argument is only necessary if
        the program has been called from another program and is reading from
        the calling program's work area.  The default is to read from the
        executing program's own work area.































          COPYWRITE 1992 - 1994 ALL RIGHTS RESERVED, FELIX JAMES   PAGE 50
        
        BAX INTERPRETER VER 2.1 FOR DOS, STATEMENTS & FUNCTIONS    PAGE 51

                                 WORKSET STATEMENT

        The WORKSET statement transfers characters specified in the WORKSET
        statement to the work area.  Two or three arguments are required.
        The first argument is the character position in the work area
        where the transfer is to begin.  The second is a word representing
        the characters to be transferred (usually a variable).  The third
        argument is a pointer to the targeted work area and is only required
        if you are writing to another program's work area. (See notes below)

        Let's say the first 40 characters of a work area are as shown
        below.  The SCALE lines of course are not actually in the work area
        and are for reference only.

        SCALE (10'S)                1         2         3         4
        SCALE (UNITS)      1234567890123456789012345678901234567890

        WORKAREA CONTENTS: APPLES    PEARS     LEMONS    ORANGES

        %C = CHERRIES
        %D = DATES
        WORKSET 11 %C     'UPDATE WORK AREA BEGINNING AT BYTE 11
        WORKSET 31 %D     'UPDATE WORK AREA BEGINNING AT BYTE 31

        The work area will now look like this.

        SCALE (10'S)                1         2         3         4
        SCALE (UNITS)      1234567890123456789012345678901234567890

        WORKAREA CONTENTS: APPLES    CHERRIES  LEMONS    DATESES

        Notice what happened at bytes 31 thru 37.  The word "DATES" is
        not long enough to overlay the word "ORANGES".  It's always a
        good idea to "blank pad" values to their full field length unless
        you know that there is no possibility that the field already
        contains data.  If the variable assigments in the above example
        has been coded like this ---

        %C = LEFT CHERRIES 10
        %D = LEFT DATES 10

        --- then the problem would not have occurred.

        If your program is a sub-routine called by another program and you
        want to write data on your caller's work area, then you must include
        the pointer to your caller's work area in your WORKSET statements.
        Simply add it as a third argument as shown below.

        WORKSET 11 %C %P  '%P IS THE POINTER TO OUR CALLER'S WORK AREA
        WORKSET 31 %D %P  '                DITTO







          COPYWRITE 1992 - 1994 ALL RIGHTS RESERVED, FELIX JAMES   PAGE 51
        
